Pular para conteúdo

Implementation Plan: Public API Build Configuration

Branch: 001-api-build-url | Date: 2026-08-04 | Spec: spec.md

Summary

Make the web artifact bind its public API destination during the image build, reject a production build without that destination, and document the corresponding Dokploy setting. The deployment smoke test verifies browser traffic uses the public API, not localhost.

Technical Context

Language/Version: TypeScript; Next.js 15.4; Node.js 22 in the web image

Primary Dependencies: Next.js App Router, pnpm, Docker

Storage: N/A

Testing: Next production build, Docker image build, local browser smoke test, deployed browser network inspection

Target Platform: Docker application on Dokploy; modern browsers

Project Type: Web application consuming a separate API service

Performance Goals: No additional request, redirect, or runtime configuration round trip

Constraints: The client-visible API address is public and therefore not a secret. It is compiled into the client bundle by Next.js and must be supplied before next build.

Scale/Scope: One web repository, its Docker build interface, and its deployment guide.

Constitution Check

Gate Status Evidence
Specification before implementation Pass spec.md is approved.
Contract-first boundary Pass build-configuration.md defines required configuration and failure behavior.
Vertical-slice verification Pass quickstart.md requires image and browser verification.
Clinical-data safety Pass Only a public service base address is configured; no secret is added.
AI-first legibility Pass One explicit configuration boundary and one documented deploy procedure.

Project Structure

Documentation

specs/001-api-build-url/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── build-configuration.md
└── tasks.md

Source Code

prontuare-web/
├── Dockerfile                 # Accepts and exposes build configuration
├── lib/api.ts                 # Resolves the client API base address
├── .env.production.example    # Documents the required public value
└── README.md                  # Dokploy deployment instructions

Structure Decision: Keep the deployment concern in the web repository. No API or database change is required because the client already has a single API base-address boundary.

Implementation Approach

  1. Define an explicit Docker build argument for the public API address and expose it only in the build stage where Next.js creates the browser bundle.
  2. Centralize API-base resolution so development retains its documented local default but a production build rejects an absent, malformed, or localhost address.
  3. Update the production example and README with the exact Dokploy Build Time Argument name, public value, and rebuild requirement.
  4. Build the image once with the production public address and assert the compiled output does not contain the localhost API address.
  5. Run a browser smoke test against the image/deployment and confirm registration or sign-in contacts the configured API host.

Complexity Tracking

No constitution violations or additional complexity are required.