Marryme

Constitution - Wedding RSVP App

Governing principles, decision hierarchy, and quality guardrails for the Wedding RSVP application.

1. Purpose

Define durable, non-ephemeral rules that guide architectural, process, and quality decisions for our wedding RSVP platform. These principles are higher-order than transient tasks or implementation details and ensure consistent, maintainable, and secure development practices.

2. Core Principles

Each principle gets a stable ID (CONST-P#) for traceability from specs, plan items, tasks, and implementation decisions.

CONST-P1: Modular Architecture First ✅ IMPLEMENTED

• MANDATORY MODULAR STRUCTURE: Break everything into small, self-contained modules with single responsibilities
• STRICT SEPARATION OF CONCERNS: UI components NEVER handle business logic or API calls directly
• FEATURE-BASED FOLDERS: Organize by features (auth, rsvp, admin, content), not file types
• CLEAN ARCHITECTURE: Separate policy from implementation details - defer technology decisions
• ✅ Implemented: src/features/ and src/shared/ structure in place

CONST-P2: AI-Driven Development Excellence ✅ IMPLEMENTED

• PLAN FIRST: Spend 60-70% of time planning architecture, UI/UX, and task breakdown before coding
• STRUCTURED PLANNING PROCESS: Constitution → Specification → Plan → Tasks → Implementation
• CONTEXT MANAGEMENT: Feed AI only relevant files/folders for current task
• NEW CONVERSATIONS: Start fresh AI conversations at natural breakpoints
• MVP MINDSET: Build simplest valuable version first, avoid scope creep
• MULTIPLE SOLUTIONS: Always ask AI for 2-3 approaches with pros/cons
• ✅ Implemented: Spec Kit process with constitution, specification, plan, tasks documents

CONST-P3: Type Safety & Validation ✅ IMPLEMENTED

• STRICT TYPESCRIPT: No any types allowed, comprehensive type definitions
• ZOD VALIDATION: All user inputs and API responses validated with Zod schemas
• COMPILE-TIME SAFETY: Catch errors at build time, not runtime
• API CONTRACTS: Type-safe API interfaces with proper error handling
• ✅ Implemented: Zod schemas for all data types, TypeScript strictness enforced

CONST-P4: Code Quality & Consistency ✅ IMPLEMENTED

• LINTERS MANDATORY: ESLint, Prettier, Tailwind CSS linter configured and enforced
• NAMING CONVENTIONS: PascalCase for components, camelCase for variables, kebab-case for files
• DRY PRINCIPLE: No duplicate logic - create reusable utilities
• SOLID PRINCIPLES: Single responsibility, open/closed, dependency inversion
• ZERO WARNINGS: All lint errors and warnings must be resolved before merge
• ✅ Implemented: All lint errors resolved, successful production build

CONST-P5: Security & Privacy by Default 🚧 PHASE 2

• INPUT SANITIZATION: Validate and sanitize all user inputs with Zod schemas
• SECURE AUTHENTICATION: JWT-based auth with httpOnly cookies, proper session management
• AUTHORIZATION CHECKS: Role-based access control on all protected routes
• NO SECRETS IN CODE: Use environment variables, never commit sensitive data
• REGULAR SECURITY AUDITS: Review critical code against security best practices
• 🚧 Planned: JWT authentication system, input validation, secure admin access

CONST-P6: Testing & Quality Assurance 🚧 PHASE 3

• UNIT TESTS REQUIRED: Every core function must have unit tests
• TDD FOR CRITICAL PATHS: Test-driven development for auth, APIs, core features
• MOCK EXTERNAL DEPS: Mock databases, third-party APIs in tests
• CI/CD AUTOMATION: Tests run automatically on every commit/PR
• TESTABLE ARCHITECTURE: Business logic testable without UI dependencies

CONST-P7: Design System & UI Excellence ✅ IMPLEMENTED

• UTILITY-FIRST CSS: Tailwind CSS with wedding-themed design system
• COMPONENT LIBRARY: Shared UI components with consistent styling
• RESPONSIVE DESIGN: Mobile-first approach with proper breakpoints
• ACCESSIBILITY: WCAG 2.1 AA compliance, keyboard navigation, screen reader support
• WEDDING THEME: Consistent color palette, typography (Inter + Playfair Display)
• ✅ Implemented: Wedding design system, shared components library

CONST-P8: API First & Service Layer 🚧 PHASE 2

• SERVICE LAYER PATTERN: All API calls go through dedicated service functions
• CUSTOM HOOKS: Business logic isolated in custom hooks, not components
• ERROR BOUNDARIES: Implement error boundaries for graceful failure handling
• LOADING STATES: Every async operation has loading, success, and error states
• API VERSIONING: Prepare for future API changes with proper versioning

CONST-P9: Performance & Scalability 🚧 PLANNED

• BUNDLE OPTIMIZATION: Code splitting, tree shaking, lazy loading
• IMAGE OPTIMIZATION: Next.js Image component, proper sizing
• CACHING STRATEGIES: API response caching, static generation where possible
• MONITORING: Error tracking, performance metrics, user analytics

CONST-P10: Documentation & Knowledge Management ✅ IMPLEMENTED

• COMPREHENSIVE README: Setup instructions, tech stack, architecture overview
• SPEC-DRIVEN DOCS: Living specification, plan, and task documentation
• CODE COMMENTS: Explain the “why” not the “what” - focus on complex logic
• ARCHITECTURAL DECISIONS: Document important design choices
• KEEP DOCS CURRENT: Update documentation with every feature change
• ✅ Implemented: Spec Kit documentation system with constitution, specification, plan, tasks

CONST-P11: Version Control & Collaboration Excellence

• GIT FROM DAY ONE: Proper version control with meaningful commits
• FEATURE BRANCH WORKFLOW: No direct commits to main branch
• MEANINGFUL COMMITS: Clear, descriptive commit messages with task references
• CODE REVIEWS: Every feature requires review before merge
• CHANGE TRACEABILITY: Every change references TASK-### and SPEC/PLAN items

CONST-P12: Deployment & Production Readiness 🚧 PHASE 5

• ENVIRONMENT PARITY: Development, staging, production environments match
• AUTOMATED DEPLOYMENT: CI/CD pipeline with proper testing gates
• HEALTH CHECKS: Monitoring, logging, error tracking in production
• BACKUP STRATEGIES: Data backup and recovery procedures
• SCALABILITY: Prepared for traffic spikes and growth

3. Decision Hierarchy

1. Constitution (this document) – Durable principles; changes require majority maintainer approval
2. Architectural Decision Records (ADRs) – Architectural decisions; may supersede Plan entries; must cite impacted CONST-P#
3. Plan (PLAN-#) – Evolving architectural blueprint; updated via PR referencing relevant ADR or SPEC
4. Specification (SPEC-#) – User-facing requirements; drives Plan evolution
5. Tasks (TASK-###) – Execution units implementing Plan/Spec items
6. Code – Implementation detail; cannot silently diverge from higher layers

4. Wedding RSVP Specific Rules

CONST-P13: Wedding Data Privacy

• GUEST DATA PROTECTION: RSVP data is sensitive personal information
• MINIMAL DATA COLLECTION: Only collect necessary information for wedding planning
• DATA RETENTION: Clear policies on how long guest data is stored
• EXPORT CAPABILITIES: Couple can export their guest data at any time
• DELETE ON REQUEST: Guests can request data deletion after wedding

CONST-P14: User Experience Excellence

• MOBILE-FIRST: Most guests will RSVP on mobile devices
• SIMPLE FLOW: RSVP process should be completed in under 2 minutes
• CLEAR FEEDBACK: Every action provides clear success/error feedback
• OFFLINE RESILIENCE: Basic functionality works without internet
• LOADING STATES: Never leave users wondering if something is processing

CONST-P15: Wedding Theme Integration

• CONSISTENT BRANDING: Wedding colors, fonts, and style throughout
• EMOTIONAL DESIGN: UI should evoke joy and celebration
• PERSONAL TOUCHES: Incorporate couple’s personality and story
• PHOTO INTEGRATION: Support for wedding photos and moments
• CELEBRATION FOCUS: Every interaction should feel celebratory

5. Quality Bars & Compliance

Area	Minimum Standard	Related Principles	Status
Architecture	Feature-based modules, clean imports	P1, P2	✅ Complete
Type Safety	Zero any types, Zod validation	P3	✅ Complete
Code Quality	Zero lint warnings, successful build	P4	✅ Complete
Security	Input validation, secure auth	P5	🚧 Phase 2
Testing	80% coverage for services	P6	🚧 Phase 3
Design	Mobile-first, accessible	P7, P14	✅ Foundation
Performance	<3s load time, optimized images	P9	🚧 Phase 4
Documentation	Living docs, clear setup	P10	✅ Complete

6. Amendment Process

• Open PR modifying constitution.md with detailed rationale
• Provide impact matrix: affected principles, migration considerations
• Require: (a) all CI green, (b) successful build, (c) maintainer approval
• On merge: update any obsolete PLAN or SPEC references within same PR

7. Enforcement Hooks

• Build Gate: Constitution compliance checked in CI/CD pipeline
• PR Template: Prompts for TASK/SPEC/PLAN references and principle compliance
• Code Reviews: Reviewers verify adherence to constitutional principles
• Documentation: All major changes reference relevant CONST-P# principles

8. Success Metrics

• Code Quality: Zero technical debt, maintainable architecture
• User Experience: <2min RSVP completion, mobile-optimized
• Security: Zero security vulnerabilities, secure data handling
• Performance: Fast loading, optimized bundle size
• Maintainability: Easy to extend, well-documented, testable

---

This constitution ensures our wedding RSVP app maintains the highest standards of quality, security, and user experience while being maintainable and scalable for future enhancements.

6. Styling & Design System

• TAILWIND UTILITY-FIRST: Use Tailwind classes for most layouts, spacing, typography.
• DESIGN SYSTEM TOKENS: Mirror colors, spacing, fonts in Tailwind config.
• RESPONSIVE DESIGN: Mobile-first with Tailwind breakpoints.
• ACCESSIBILITY: Sufficient color contrast, focus styles, keyboard navigation.
• CSS MODULES: For complex component styles not achievable with utilities.

7. Version Control & Collaboration

• GIT FROM DAY ONE: Initialize repository before writing any code.
• FEATURE BRANCH WORKFLOW: No direct commits to main branch.
• MEANINGFUL COMMITS: Clear, descriptive commit messages.
• CODE REVIEWS MANDATORY: Every feature branch requires review before merge.
• REGULAR COMMITS: Commit at natural breakpoints, not just at end of day.

8. Documentation & Knowledge Management

• COMPREHENSIVE README: Setup instructions, tech stack, architecture overview.
• CODE COMMENTS: Explain the “why” not the “what” - focus on complex logic.
• ARCHITECTURAL DECISIONS: Document important design choices (ADRs).
• KEEP DOCS CURRENT: Update documentation with every feature change.

9. Performance & Scalability

• CODE SPLITTING: Lazy loading, dynamic imports.
• OPTIMIZATION: Image optimization, caching strategies.
• MONITORING: Logging, error tracking, performance metrics.

Tech Stack Commitments

• Frontend: Next.js 15+, TypeScript, Tailwind CSS v4
• Backend: Next.js API routes (serverless)
• Database: JSON file (for MVP), upgrade to SQLite/PostgreSQL later
• Testing: Jest, React Testing Library
• Linting: ESLint, Prettier
• Deployment: Vercel/Netlify

Development Process

• Spec-Driven Development: Use Spec Kit for planning and implementation
• AI-Assisted Coding: Leverage GitHub Copilot with structured prompts
• Iterative Development: MVP first, then enhance features
• Quality Gates: Tests pass, linting clean, security audit before merge

Success Metrics

• Code Coverage: >80% unit test coverage
• Performance: Lighthouse score >90
• Accessibility: WCAG 2.1 AA compliance
• Security: No high/critical vulnerabilities
• User Experience: Intuitive, responsive, fast-loading