gitadmin/sass-imobiliaria
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
sass-imobiliaria/.specify/memory/constitution.md

8.4 KiB
Raw Blame History

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