# saas_imobiliaria Constitution ## Core Principles ### I. Design-First All UI components and pages MUST conform to `DESIGN.md` — the Linear-inspired dark design system defined at the project root. - Background canvas: `#08090a`; panel: `#0f1011`; elevated surface: `#191a1b` - Typography: Inter Variable exclusively, with OpenType features `"cv01", "ss03"` enabled globally - Signature weight 510 for body UI text; aggressive negative letter-spacing at display sizes - Brand accent: `#5e6ad2` (backgrounds) / `#7170ff` (interactive) / `#828fff` (hover) — the only chromatic color - Borders MUST use semi-transparent white: `rgba(255,255,255,0.05)` to `rgba(255,255,255,0.08)` - Visual precision is non-negotiable: spacing, sizing, and color values MUST match DESIGN.md exactly - No one-off inline styles that deviate from the design system; extract to Tailwind config or CSS variables **Rationale**: Visual consistency is a core product value. Deviations accumulate into an incoherent UI that erodes user trust. ### II. Separation of Concerns Flask and React MUST remain strictly decoupled. The boundary between them is a versioned JSON REST API. - Flask API: pure REST JSON responses only — no HTML rendering, no templating, no Jinja2 in API routes - React frontend: a Single Page Application (SPA) — all routing, state, and rendering happen in the browser - No server-side rendering; no mixed rendering strategies - API contract (request/response shapes) MUST be documented before implementation begins - The frontend MUST NOT import or depend on backend code and vice versa - CORS configuration MUST be explicit; never use wildcard origins in production **Rationale**: Tight coupling between Flask and React creates brittle codebases that are hard to test, deploy, and evolve independently. ### III. Spec-Driven Development (NON-NEGOTIABLE) Every feature MUST have a `spec.md` approved before any implementation code is written. The order is always: **spec → plan → tasks → implement** — no exceptions. - "Free coding" — writing implementation code without a prior spec — is prohibited - Spec MUST include user stories with acceptance scenarios before a plan is created - Implementation MUST NOT begin until tasks are derived from the plan - Refactors and fixes of non-trivial scope also require a spec entry - The spec is the source of truth; implementation follows the spec, not the other way around **Rationale**: Unspecified features create unpredictable scope, poor handoffs, and untestable outcomes. The spec-first cycle forces clarity before cost. ### IV. Data Integrity All property (imóvel) data flowing into the system MUST be validated at the API boundary using Pydantic models. - Every Flask route that accepts input MUST validate with a Pydantic schema — no manual `request.json` field access - Database schema changes MUST be managed via Flask-Migrate/Alembic migrations — no ad-hoc `CREATE TABLE` or `ALTER TABLE` - Raw SQL is prohibited in application code; use SQLAlchemy ORM for all queries - Nullable fields MUST be explicitly declared; no implicit nullability - Sensitive fields (e.g., prices, area measurements) MUST use appropriate numeric types — no float for money **Rationale**: Imóvel data represents real financial and legal information. Silent data corruption or type coercion errors have real-world consequences. ### V. Security All admin panel routes MUST require authentication. No sensitive configuration may exist outside environment variables. - Admin API endpoints MUST be protected; unauthenticated requests MUST return `401`, not redirect - Secrets (database URLs, JWT keys, API tokens) MUST be loaded from environment variables — never hardcoded or committed - The React frontend MUST NOT contain secrets, tokens, or credentials — only public configuration - CSRF protection MUST be enabled for all state-mutating routes - File uploads (e.g., property images) MUST validate MIME type and enforce size limits - Dependencies MUST be pinned; `uv.lock` and `package-lock.json` MUST be committed and kept up to date **Rationale**: Admin panels and property data are high-value targets. Security is a baseline requirement, not an optional layer. ### VI. Simplicity First The simplest solution that correctly fulfills the spec MUST be preferred. Complexity requires explicit justification. - KISS: if a simple approach works, it ships; clever solutions require written rationale in the spec or plan - YAGNI: do not build for hypothetical future requirements; build for the current spec only - No premature abstraction: helpers, base classes, and shared utilities are created only when the duplication is real (≥3 concrete uses) - Configuration-driven behavior is an abstraction — it requires justification - Dependencies MUST earn their place: each new package requires a stated reason in the plan **Rationale**: Imobiliária SaaS is a well-scoped domain. Over-engineering early locks the codebase into complexity that slows all future work. ## Stack Constraints The following technology choices are locked for this project. Deviations require a constitution amendment. | Layer | Technology | Notes | |---|---|---| | Backend language | Python 3.12 | Managed via `uv` | | Backend framework | Flask | REST API only; no SSR | | Data validation | Pydantic v2 | All API input/output schemas | | ORM | SQLAlchemy | Via Flask-SQLAlchemy | | Migrations | Flask-Migrate / Alembic | No raw DDL in app code | | Database | PostgreSQL | Local dev via Docker | | Frontend framework | React 18+ (TypeScript) | SPA; strict mode enabled | | Build tool | Vite | Frontend bundler | | Styling | Tailwind CSS | Config aligned with DESIGN.md tokens | | Python package manager | uv | `uv.lock` committed | | Node package manager | npm | `package-lock.json` committed | No alternative framework, ORM, or package manager may be introduced without amending this document. ## Development Workflow All development follows the spec-driven cycle defined in Principle III: 1. **Spec** (`/speckit.specify`): Write `specs/###-feature/spec.md` with user stories and acceptance scenarios 2. **Plan** (`/speckit.plan`): Derive technical approach, data model, and API contracts from the spec 3. **Tasks** (`/speckit.tasks`): Break the plan into concrete, independently implementable tasks 4. **Implement**: Execute tasks in order; each task targets a specific file or endpoint Additional workflow rules: - All work MUST happen on a feature branch; no direct commits to `main` - Commits MUST follow Conventional Commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:` - Run the full backend test suite (`uv run pytest`) and frontend build (`npm run build`) locally before pushing - Database migrations MUST be tested with an upgrade + downgrade cycle locally before commit - UI changes MUST be visually verified against DESIGN.md before the branch is considered complete ## Governance This constitution supersedes all other practices, preferences, and conventions in this project. When a conflict arises between any other document and this constitution, this constitution wins. - All feature work begins with a constitution check: does the plan comply with all six principles? - Amendments to this constitution MUST be documented with a version bump (see versioning rules below) - Versioning policy: - **MAJOR**: Removal or redefinition of a core principle; breaking change to the stack constraints - **MINOR**: New principle or section added; material expansion of existing guidance - **PATCH**: Clarifications, wording improvements, typo fixes - Amendment procedure: update this file, increment the version, record the change in the Sync Impact Report comment block, commit with message `docs: amend constitution to vX.Y.Z (

)` - Constitution compliance MUST be reviewed at the start of every plan and before any PR is merged **Version**: 1.0.0 | **Ratified**: 2026-04-13 | **Last Amended**: 2026-04-13