Constru Platform — Architecture

System Architecture

Constru platform diagram: web and mobile clients, API, database, and third-party services

Three applications share one API: Constru API (Fastify, Node.js), Constru Web (Next.js), and Constru Mobile (Expo). The API covers authentication (JWT), lots, houses, rooms, construction budgets, payments through Mercado Pago, budget PDF rendering (Puppeteer), and transactional email (Brevo HTTP API).

Backend Architecture

Constru API layers: Fastify controllers, use cases, repositories, and external services

Clean-style layout: HTTP controllers, Prisma repositories, use cases, and integration services (payments, email, PDF). Fastify with CORS, JWT, authenticated route guards, and static assets where needed. Prisma ORM on PostgreSQL. Core entities: User (roles USER | ADMIN | MASTER), Lot, House, Room with RoomType, HouseBudget, AppServiceFee, Payment.

Frontend (Web) Architecture

Next.js App Router, forms, house visualization, and payment UI flow

Next.js App Router. Primary routes include home, authentication (sign-in, sign-up, password recovery), role dashboards (admin, master), house flows (create, update by lot, budget per house), and payment journeys (method selection, PIX, card, boleto, success/failure/pending). Feature components include LotForm, RoomsForm, and HouseVisualization (drag-and-drop with dnd-kit).

Mobile Architecture

Mobile stack: Expo Router, Redux, secure auth storage, API client, Sentry

Expo Router for navigation, Redux Toolkit with Redux Persist for state, secure storage for JWTs, and an API client aligned with the same backend as the web app. Screens cover lots, houses, room editing, budget review, and payment outcomes; PDFs can be opened or downloaded after generation. Sentry instruments crashes and breadcrumbs for production diagnostics.

Database Model

Database entities for users, lots, houses, rooms, budgets, fees, and payments

Relational model in PostgreSQL via Prisma. User: email, profile fields, role. Lot: dimensions and total area per owner. House: belongs to a user and a lot; name and total area. Room: width, height, position (x, y), rotation angle, and RoomType. HouseBudget: construction cost per house. RoomPrice: price per square metre by room type. AppServiceFee: configurable service fees. Payment: amount, status, optional Mercado Pago payment id, links to user, service fee, and optionally a house.

API Design & Authentication

API modules for auth, lots, houses, rooms, pricing, payments, and webhooks

REST JSON API. Authentication: POST /signin (email, password) returns a JWT; sign-up, password recovery, and email checks live under the same surface. Authenticated requests send Authorization: Bearer <token>. House and budget assets: for example GET /houses/:houseId/budget/pdf and POST /houses/:houseId/budget/layout-image. Authenticated users call POST /payments/mercadopago; GET /payments/success|failure|pending are redirect targets after checkout. Server-to-server: POST /webhook/mercadopago.

Deployment Architecture

Hosting layout: Railway for web, EAS for mobile, API and PostgreSQL on cloud or containers

The API runs in Node.js on Railway with DATABASE_URL, JWT_SECRET, and provider keys (Mercado Pago, Brevo, public URLs for webhooks). Constru Web is hosted on Railway. Constru Mobile ships with EAS Build and can use EAS Update for over-the-air JavaScript updates.

Payments & Webhooks Flow

Payment checkout, provider webhooks, database update, PDF generation, and email

The client starts checkout through the API (Mercado Pago). The user browser is redirected to success, failure, or pending URLs while the payment provider notifies the backend asynchronously via webhooks. On approval, the service updates Prisma, renders the budget PDF with Puppeteer, and sends it by email through Brevo. Web and mobile clients download or display the PDF through authenticated API routes.