# Architecture Decisions ## ADR 1: Adoption of Next.js as Frontend Framework **Context** The project needs a modern frontend framework with server-side rendering, good performance, SEO support, scalability, and simple deployment. The team evaluated React, Angular, Vue, and Next.js. **Decision** The frontend will use Next.js because it provides built-in SSR, SSG, routing, and API routes that align well with the project requirements. **Status** Accepted **Consequences** - Positive: better performance, stronger SEO support, a mature ecosystem, and simpler routing and full-stack integration - Negative: a learning curve for developers new to Next.js and a more opinionated project structure - Neutral: continued dependency on the React ecosystem ## ADR 2: Adoption of Python with FastAPI for Backend Services **Context** The project needs a backend that is performant, maintainable, scalable, type-safe, and easy to document. The team evaluated Node.js, Java, and Python frameworks including Django and Flask. **Decision** The backend will use Python with FastAPI because it offers high performance, async support, Pydantic validation, automatic OpenAPI documentation, and a clean developer experience. **Status** Accepted **Consequences** - Positive: fast async request handling, generated API documentation, strong validation, and rapid development in Python - Negative: a smaller ecosystem than some enterprise frameworks and a need to understand async patterns - Neutral: dependency on the Python runtime and ecosystem ## ADR 3: Usage of pnpm as Package Manager **Context** The project needs a package manager that is performant, maintainable, scalable, and easy to use. The team evaluated npm, yarn, and pnpm. **Decision** The project currently leans toward pnpm as the package manager for frontend workflows and dependency management. **Status** Accepted **Consequences** - Positive: pnpm is fast and efficient with a smaller disk footprint - Negative: it has a smaller ecosystem footprint than npm - Neutral: adoption continues to grow and the tooling is actively maintained ## ADR 4: Database Technology **Context** The project needs a persistent database for users, sessions, and match data. The main decision is NoSQL versus relational storage. The team evaluated MongoDB for NoSQL and MariaDB/PostgreSQL for relational options. **Decision** The project will use a relational database. The domain model is strongly structured (users, matches, scores, and session relations), and consistency is important for game state and ranking data. PostgreSQL was selected because it is reliable, well-known by the team, and provides strong SQL capabilities for future analytics and reporting needs. **Status** Accepted **Consequences** - Positive: strong data integrity guarantees, rich querying, and mature operational tooling - Negative: schema migrations and relational modeling add design and maintenance overhead - Neutral: development workflows include SQL and migration tooling as standard practice ## ADR 5: ORM vs Writing SQL Queries **Context** The backend needs a consistent and maintainable way to access relational data. The team evaluated two approaches: writing raw SQL queries for all operations or using an ORM with typed schemas and validation. **Decision** The project will use an ORM-first approach with SQLAlchemy for data access and Pydantic for request/response and domain validation. Raw SQL can still be used for performance-critical or highly specialized queries when needed. **Status** Accepted **Consequences** - Positive: improves developer productivity, consistency, and readability in CRUD and relationship-heavy operations - Negative: adds ORM abstraction overhead and requires careful query tuning to avoid performance pitfalls - Neutral: team workflows include SQLAlchemy models and Pydantic schemas as standard backend patterns ## ADR 6: WebSocket vs API Polling for Game Communication **Context** The project needs a communication pattern for the multiplayer game mode. Gameplay events such as match state updates, countdowns, and answer submissions must be delivered with low latency and in near real time. **Decision** The project will use WebSockets as the primary communication channel for battle mode runtime events. HTTP API endpoints remain in use for non-realtime operations such as authentication, setup, and historical data retrieval. **Status** Accepted **Consequences** - Positive: supports bidirectional low-latency communication and improves realtime user experience in matches - Negative: introduces additional complexity for connection lifecycle, reconnect handling, scaling, and monitoring - Neutral: requires team familiarity with event-driven patterns while existing REST endpoints continue to be used where appropriate ## ADR 7: Authentication with Google OAuth **Context** The project currently uses Google OAuth for authentication, but the team is evaluating whether to keep that setup or move to a different authentication approach. A major concern is testability: a custom provider would be easier to control and mock in Playwright than Google OAuth. **Decision** The current implementation uses Google OAuth for sign-in, and the backend creates and refreshes application sessions after a successful login. The long-term authentication strategy is still under review, with better automated testability as one of the key decision factors. **Status** Pending **Consequences** - Positive: reduces custom security work compared with a fully self-managed credential flow. - Positive: a custom provider would be easier to mock in Playwright-based end- to-end tests. - Negative: continuing with Google keeps the auth flow dependent on an external service and makes browser automation harder to isolate. - Neutral: the backend still manages application sessions and authorization for protected routes.