Skip to content

constitution.md

Latest commit

 

History

History
135 lines (102 loc) · 5.93 KB

constitution.md

File metadata and controls

135 lines (102 loc) · 5.93 KB

Payment Request — Project Constitution

Core Principles

I. Spec as Source of Truth

All features must be defined in the spec before implementation begins. Code without a corresponding spec entry is unauthorized. Ambiguities in requirements must be resolved through explicit, documented assumptions — never inferred silently.

II. AI-First, Human-Governed Development

AI tools are used aggressively for generating specs, code, scaffolding, and tests. However, no AI-generated output is accepted without human review. The human is the final authority on correctness, architecture, constraints, and validation. AI accelerates — the human governs.

III. Prefer Simplicity Over Completeness

Build the minimum system that satisfies the spec. Do not introduce:

  • Background job systems, message queues, or worker pools
  • External service integrations beyond what is specified
  • Premature abstractions or "future-proofing" layers

If it's not in the spec, it doesn't get built.

IV. Explicit Fintech Domain Modeling

Caution

Money handling errors are unacceptable. These rules are non-negotiable.

  • Money representation: Use integer cents (or equivalent precise type). No floating-point arithmetic for monetary values.
  • Payment request states are strictly defined and enforced: 
    PENDING → PAID
PENDING → DECLINED
PENDING → EXPIRED
PENDING → CANCELED
  • Terminal states (PAID, DECLINED, EXPIRED, CANCELED) are immutable. No transitions out of terminal states are permitted.
  • Invalid state transitions must be rejected with an explicit error.

V. Deterministic System Behavior

Every user action must produce a predictable, reproducible state change. Simulated processes (e.g., payment fulfillment) must:

  • Include clear loading/processing states
  • Produce deterministic outcomes (no random failures in happy paths)
  • Complete within defined time bounds (2–3 seconds for payment simulation)

VI. End-to-End Testing of Critical Flows

E2E tests are mandatory for all core user flows:

  • Request creation
  • Payment fulfillment
  • Request decline
  • Request expiration
  • Request cancellation

Tests must be automated, produce video recordings, and run without manual intervention.

VII. Single Source of Data Truth

All views — sender dashboard, recipient dashboard, request detail — must derive from the same underlying data model. There must be no duplicated or conflicting state across views. If the sender sees "Paid", the recipient sees "Paid" — always.

VIII. Development Speed as a Priority

Ship a working system quickly. Use AI tools for:

  • Scaffolding and boilerplate
  • Repetitive implementation patterns
  • Test generation
  • Documentation drafting

Avoid overengineering. A working prototype today is better than a perfect architecture tomorrow.

IX. Separation of Concerns

Maintain clear logical boundaries, even within a single codebase:

Layer Responsibility
UI / Presentation Rendering, user interaction, routing
Domain Logic State machines, validation, business rules
Data Access Persistence, queries, data transformation

No layer should bleed into another. Domain logic must not contain UI concerns. Data access must not contain business rules.

X. Explicit Assumptions

All behavior not explicitly defined in the spec must be resolved through documented assumptions. Hidden or implicit assumptions are prohibited.

Assumptions must be:

  • Written down in the spec or a dedicated assumptions section
  • Reviewable and challengeable
  • Traceable to the decision they inform

XI. Demo-First Product Design

The system must be immediately testable without external setup:

  • Seeded demo users with pre-populated data
  • Predictable, repeatable flows
  • No dependency on external APIs, email services, or third-party auth for demo evaluation
  • A public URL that is testable without local development setup

Development Standards

Technology & Stack Discipline

  • Use the project's chosen stack consistently. Do not introduce new frameworks or libraries without justification.
  • Follow framework idioms and conventions — no custom alternatives for solved problems.
  • All secrets and configuration via environment variables. No hardcoded credentials.

Code Quality Gates

  • Input validation: All user inputs validated at the boundary (type, format, range).
  • Error handling: Actionable error messages. No silent failures.
  • Structured logging: JSON logs with correlation IDs where applicable.
  • Responsive design: All UI must work on both mobile and desktop viewports.

Data & Persistence

  • Schema-first approach: define data models before writing queries.
  • Monetary values stored as integers (cents).
  • Timestamps in UTC with timezone-aware formatting for display.
  • Request expiration: 7 days from creation, enforced at query time.

Workflow

Spec-Kit Driven Process

  1. Specify — Define features in the spec with clear acceptance criteria
  2. Plan — Break the spec into an implementation plan with ordered tasks
  3. Implement — Build against the plan using AI-assisted development
  4. Test — Automated E2E tests with recordings for all critical flows
  5. Validate — Human review of AI output, test results, and deployed behavior

Change Protocol

  • No code changes without a corresponding spec or plan entry
  • All spec ambiguities resolved and documented before implementation
  • Terminal state transitions tested before any PR is merged

Governance

  • This constitution supersedes all ad-hoc practices and informal agreements.
  • All implementation work must verify compliance with these principles.
  • Amendments require: documentation of the change, rationale, and impact assessment.
  • Complexity must be justified against these principles — if a principle says "simple", prove the complexity is necessary.

Version: 1.0.0 | Ratified: 2026-04-09 | Last Amended: 2026-04-09