Important architecture decisions are documented as Architecture Decision Records (ADRs). Each ADR follows a consistent template covering context, decision, rationale (with alternatives considered), and consequences.
The technology stack was chosen to balance developer productivity, performance, and alignment with the project's educational and quality assurance goals:
Layer
Technology
Rationale
Backend Framework
FastAPI (Python 3.14)
Async-native, automatic OpenAPI docs, Pydantic validation, high performance
Authentication
fastapi-users + JWT
Production-ready user management, secure defaults, extensible
Frontend Framework
SvelteKit (Svelte 5)
Compile-time optimizations, minimal bundle size, no virtual DOM
Backend follows a three-layer pattern: Router → Service → Repository. Each layer has a single responsibility and is independently testable.
Interface Abstraction
Gas station data provider and data export are abstracted behind interfaces (ABCs), enabling easy swapping of implementations and advanced API drop out handling.
Database Cache
Tankerkönig API responses are cached in PostgreSQL with spatial and temporal metadata, reducing external API calls.
Graceful Degradation
When the Tankerkönig API is unavailable, the system returns an empty result list rather than failing.
Rate Limiting
Two-level rate limiting: per-user (SlowAPI) for the nearby stations endpoint, and global token-bucket for Tankerkönig API calls.
Invitation-Only Registration
User registration requires a valid invitation key, preventing unrestricted public signup.
Dual DB Support
The backend supports both PostgreSQL (production) and SQLite (development/testing) via a common async SQLAlchemy interface.
Docker Compose Deployment
All services (backend, frontend, database, monitoring) run in Docker containers, ensuring consistent environments.