146 lines
8.4 KiB
Markdown
146 lines
8.4 KiB
Markdown
<!--
|
||
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
|
||
|
||
### 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 (<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
|