feat: add full project - backend, frontend, docker, specs and configs

.specify/memory/constitution.md

@@ -1,50 +1,146 @@
-# [PROJECT_NAME] Constitution
-<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
+<!--
+SYNC IMPACT REPORT
+==================
+Version change: (new) → 1.0.0
+Added sections: Core Principles (I–VI), Stack Constraints, Development Workflow, Governance
+Modified principles: N/A (initial constitution)
+Removed sections: N/A (initial constitution)
+Templates requiring updates:
+  ✅ plan-template.md — Constitution Check gate references principles I–VI
+  ✅ spec-template.md — no structural changes required; aligns with spec-driven principle III
+  ✅ tasks-template.md — no structural changes required; aligns with existing task format
+Deferred TODOs: none
+-->
+
+# saas_imobiliaria Constitution
 
 ## Core Principles
 
-### [PRINCIPLE_1_NAME]
-<!-- Example: I. Library-First -->
-[PRINCIPLE_1_DESCRIPTION]
-<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
+### I. Design-First
 
-### [PRINCIPLE_2_NAME]
-<!-- Example: II. CLI Interface -->
-[PRINCIPLE_2_DESCRIPTION]
-<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
+All UI components and pages MUST conform to `DESIGN.md` — the Linear-inspired dark design system defined at the project root.
 
-### [PRINCIPLE_3_NAME]
-<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
-[PRINCIPLE_3_DESCRIPTION]
-<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
+- 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
 
-### [PRINCIPLE_4_NAME]
-<!-- Example: IV. Integration Testing -->
-[PRINCIPLE_4_DESCRIPTION]
-<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
+**Rationale**: Visual consistency is a core product value. Deviations accumulate into an incoherent UI that erodes user trust.
 
-### [PRINCIPLE_5_NAME]
-<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
-[PRINCIPLE_5_DESCRIPTION]
-<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
+### II. Separation of Concerns
 
-## [SECTION_2_NAME]
-<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
+Flask and React MUST remain strictly decoupled. The boundary between them is a versioned JSON REST API.
 
-[SECTION_2_CONTENT]
-<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
+- 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
 
-## [SECTION_3_NAME]
-<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
+**Rationale**: Tight coupling between Flask and React creates brittle codebases that are hard to test, deploy, and evolve independently.
 
-[SECTION_3_CONTENT]
-<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
+### 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
-<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
 
-[GOVERNANCE_RULES]
-<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
+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.
 
-**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
-<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
+- 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 (<summary>)`
+- 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