Comprehensive Hydrogeology SaaS Development

# Full-Stack Developer — B2B SaaS for Water Well Management (Implementation on Existing Architecture)

## About us

We are a Brazilian water well drilling and maintenance company digitizing our entire operation — and building it as a multi-tenant SaaS from day one, with the goal of later offering the platform to other companies in our industry. We operate in Brasília, Brazil (UTC-3).

## What we are building

A B2B operations platform that sits at the intersection of three product categories:

1. **Field service management** (think ServiceTitan / Jobber, but for water wells): customers, work orders, field crews, equipment, field bulletins, a future offline-first mobile app for technicians.
2. **Contract & progress-measurement billing** (think Procore's commercial flow): versioned proposals, contracts with line items, amendments, field work measured against contract items, approval workflow, invoicing, Brazilian tax documents (NFS-e) and payment reconciliation.
3. **Water telemetry** (think HydroVu / AQUARIUS): continuous time series from field probes (water level, flow, conductivity, temperature), quality flags, provenance, alert rules.

Around this core: a CRM with customer dossiers and conversation history, document management on Google Drive (metadata in Postgres, binaries in Drive), Telegram bots (customer-facing for billing/status, internal for alerts and queries), payment collection through the **Asaas** gateway (Pix, boleto — webhooks), and later an MCP server so AI agents can query the platform under strict policies, plus RPA automation for Brazilian water-rights agencies.

## What already exists (read carefully — this defines the job)

We have a **versioned architecture and data-model baseline (v3.0.0 handoff package)** produced and validated statically. It contains:

- PostgreSQL/PostGIS **multi-tenant relational model**: ~147 tables across 19 domain schemas (platform, IAM, registry, CRM, commercial, operations, hydrogeology, observations, measurement, finance, post-construction, documents, integration, audit, MCP);
- **12 migrations** with tenant isolation enforced by Row-Level Security **and** composite foreign keys `(tenant_id, id)` on every tenant-scoped reference;
- seeds, SQL tests, invariants and **state machines** documented per domain;
- initial **OpenAPI 3.1 contract** (16 operations) and an **MCP tool catalog** with access policies;
- inbox/outbox event pattern with idempotency, audit and data-classification policies;
- Google Drive folder templates and a dry-run provisioning script;
- ADRs recording the closed architectural decisions.

**This engagement is about implementing the application layer on top of this baseline — NOT redesigning the data model.** Proposals to "start simple with Firebase/MongoDB" or rebuild the schema are an automatic no. Evolving the model through new migrations, with justification, is expected and welcome.

## Scope of the first engagement (paid pilot, fixed scope)

1. **Database bring-up:** run all migrations on a real PostgreSQL/PostGIS instance (Docker locally, Cloud SQL for dev), fix any issues via *new* migrations, get the provided SQL tests passing (RLS isolation, composite FKs, business sequences).
2. **Project foundation:** monorepo setup, CI (GitHub Actions), dev environment, secret management, linting/test conventions.
3. **One thin vertical slice, end-to-end, with tests:**
authentication → tenant resolution → customer dossier creation → an authorized "work order status" query (respecting RLS + permission matrix) → audit log of the disclosure → exposure through the OpenAPI endpoints.
4. **Deployment of this slice to GCP Cloud Run** (API + database connectivity + Secret Manager), with basic observability (structured logs, error reporting).

**Acceptance criteria:** migrations apply cleanly from zero; SQL tests pass; the vertical slice works through the API with automated tests; RLS proven by a cross-tenant access test; deployed and reachable in a dev environment; README updated so another developer can onboard in under one hour.

Estimated effort: [YOUR ESTIMATE — e.g., 3–5 weeks]. Budget for the pilot: [YOUR BUDGET / or "please propose"].

## Roadmap after the pilot (awarded based on pilot performance)

Phase 2 — Asaas integration (webhook inbox, charge mirroring, reconciliation with receipts) · Phase 3 — internal Telegram bot (alerts, queries) · Phase 4 — water-rights/licensing entities with expiry alerts · Phase 5 — telemetry ingestion (device registry, raw payload inbox, alert engine) · Phase 6 — offline-first field app · Phase 7 — customer Telegram bot + reports (PDF) · Phase 8 — MCP server · Phase 9 — RPA for agency portals. This is a long-term, multi-phase project for the right person or small team.

## Fixed tech stack

- **Database:** PostgreSQL 16 + PostGIS (Cloud SQL in production)
- **Backend:** Node.js + TypeScript (NestJS preferred; we will discuss module layout mirroring the domain schemas)
- **Frontend:** React + TypeScript (Next.js), shadcn/ui, Tailwind; Tremor-style dashboards; design north star: Linear — clean, fast, information-dense B2B admin
- **Infra:** GCP — Cloud Run (services + jobs), Pub/Sub, Cloud Scheduler, Secret Manager, Cloud SQL
- **Integrations:** Telegram Bot API, Asaas (payments, webhooks), Google Drive API (service account), later MCP
- **Non-negotiable principles:** all access through the API/application services (bots and integrations never touch the database directly); tenant comes from the authenticated context, never from the request body; webhook processing is idempotent (inbox pattern); domain events via outbox; AI tools never execute arbitrary SQL.

## Must-have skills

- Advanced PostgreSQL in production: Row-Level Security, composite keys, migration discipline, query planning
- Real multi-tenant SaaS experience (you can explain how you prevented cross-tenant leaks)
- TypeScript across the stack; NestJS or comparable modular backend architecture
- Webhook/event-driven integration patterns with idempotency
- Automated testing culture (unit + integration against a real Postgres)

## Nice-to-have

PostGIS · GCP (Cloud Run, Pub/Sub) · Telegram bots · payment gateways · IoT/time-series ingestion · field-service or construction-tech domain · offline-first mobile (React Native/Expo) · experience working from an OpenAPI-first contract.

## Language requirement (critical filter)

The database schema, domain vocabulary, documentation and product UI are in **Brazilian Portuguese** (`cadastro.parte`, `medicao.boletim_medicao`, …). You must be comfortable working in a Portuguese-language codebase. **Brazilian / Portuguese-speaking developers are a strong plus.** Communication with me can be in Portuguese or English.

## Working model

Milestone-based contract through this platform · code in our GitHub organization from day one · pull-request reviews (I review with AI assistance and an architecture checklist) · short async updates 2–3×/week, one weekly call · preference for ≥4h overlap with UTC-3.

## Selection process

1. Short reply describing your most similar multi-tenant/Postgres project and what you'd watch out for in ours.
2. Shortlisted candidates receive the full handoff package (docs + migrations) under the platform's confidentiality terms and return: (a) questions/risks you identified, (b) your plan and estimate for the pilot. The quality of your questions matters as much as the estimate.
3. Interview (technical, 45 min) and pilot award.

## What we provide

The complete v3.0.0 handoff package (docs, ADRs, migrations, seeds, SQL tests, OpenAPI, MCP catalog, Drive templates), a macro capability map of the whole platform, GCP project access, Asaas sandbox, and a responsive product owner who knows the domain deeply and answers fast.