## 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