raceplanner/openspec/changes/new-raceplanner-app/design.md

Context

This is a new race planning application built from scratch. The system needs to support two primary user types: organizers who create and manage events, and participants who register for and attend events. The application requires user authentication, event management, registration workflows, payment tracking, and communication features.

Goals / Non-Goals

Goals:

• Build a full-stack web application with clear separation of concerns
• Implement secure user authentication with role-based access
• Create intuitive event management for organizers
• Enable seamless participant registration workflow
• Provide real-time dashboard metrics
• Support payment tracking (initially manual recording, extensible to online payments)

Non-Goals:

• Real-time chat or messaging between users
• Complex payment processing integration (Phase 1 is manual tracking only)
• Mobile native apps (web-responsive only)
• Social media integrations
• Advanced analytics or reporting (basic metrics only)

Decisions

Architecture: Full-stack with REST API

Decision: Use a client-server architecture with a REST API backend and SPA frontend.

Rationale: This provides clear separation of concerns, enables independent development of frontend and backend, and supports future mobile app development if needed.

Alternatives considered:

• Server-side rendered (SSR) application - Rejected: Less interactive UI, harder to build dashboard features
• GraphQL API - Rejected: Adds complexity, REST is sufficient for current requirements

Tech Stack: .NET Backend + Next.js Frontend (Bun Runtime)

Decision:

• Backend: .NET (C# with ASP.NET Core Web API)
• Frontend: Next.js with TypeScript, running on Bun runtime (instead of Node.js)

Rationale:

• .NET Backend: Robust framework with excellent performance, built-in dependency injection, Entity Framework Core for PostgreSQL integration, and strong typing with C#
• Next.js on Bun: Bun provides faster startup times and better performance than Node.js, while Next.js offers excellent React framework with SSR/SSG capabilities
• Full-stack TypeScript experience (C# on backend, TypeScript on frontend)
• Clear separation allows independent scaling and deployment

Alternatives considered:

• Python/Django - Rejected: Less suitable for real-time dashboard updates
• Node.js backend - Rejected: Prefer .NET's strong typing and enterprise features
• Node.js runtime for frontend - Rejected: Bun offers better performance for Next.js

Database: PostgreSQL

Decision: Use PostgreSQL as the primary database with normalized schema.

Rationale: ACID compliance for financial data (payments), mature ecosystem, good ORM support.

Alternatives considered:

• MongoDB - Rejected: Less suitable for relational data (users, events, registrations)
• SQLite - Rejected: Won't scale to multiple concurrent organizers

Authentication: JWT with httpOnly cookies

Decision: Use JWT tokens stored in httpOnly cookies for session management.

Rationale: Stateless authentication, secure against XSS, supports role-based claims.

Alternatives considered:

• Session-based auth - Rejected: Requires server-side session store, adds complexity
• OAuth only - Rejected: Still need local auth for initial version

Payment Tracking: Manual + Extensible

Decision: Start with manual payment recording, design for future integration.

Rationale: Faster MVP, payment processing can be added later without schema changes.

Risks / Trade-offs

Risk: Payment data security without integrated processor Mitigation: Encrypt sensitive fields, audit logs, plan for processor integration in Phase 2

Risk: Dashboard performance with many events/registrations Mitigation: Implement pagination, consider caching layer for metrics, database indexing

Risk: Email delivery reliability Mitigation: Use transactional email service (SendGrid/Mailgun), implement retry logic

Trade-off: Manual payment recording requires organizer trust Acceptance: Documented limitation for MVP, roadmap includes automated processing

Migration Plan

Not applicable - this is a new application with no existing data to migrate.

Deployment strategy:

1. Deploy database schema
2. Deploy backend API
3. Deploy frontend application
4. Configure DNS and SSL
5. Create initial admin user

Open Questions (Resolved)

Decision Log:

1. Email verification before allowing registration?

   • Decision: Not needed for MVP
   • Rationale: Keep signup friction minimal for initial launch; can add later if needed

2. Event categories/tags for filtering?

   • Decision: Yes, implement event categories/tags
   • Rationale: Improves event discoverability and participant experience

3. Can participants edit registrations after submission?

   • Decision: Yes, support registration cancellation
   • Rationale: Users need flexibility to manage their commitments

4. File uploads (event images, participant documents)?

   • Decision: Not needed for MVP
   • Rationale: Keep initial scope focused; can add as separate feature later