Initial commit: raceplanner project scaffold

2026-04-03 20:43:01 +02:00
commit fbfa367c16
25 changed files with 1795 additions and 0 deletions
@@ -0,0 +1,115 @@
+## 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