How joinee-im/backend works
Project type and purpose
• Jöinee is a standalone backend microservice written in Python (3.10) that exposes HTTP endpoints (OpenAPI/Swagger docs at /api/docs).
• Its core purpose is to manage reservations, venues, accounts, email verifications, file uploads, calendars, etc., and to integrate with external services (Google Calendar, Google Maps, OAuth2, Google Cloud Storage).
High‑level architectural layers
• Presentation/API layer: app/main.py + FastAPI (or Starlette) HTTP endpoints under app/processor/http
• Cross‑cutting concerns/middleware: authentication, headers, request/response logging
• Domain & business logic: app/base, app/utils, app/processor (DTOs, VO, use‑cases)
• Infrastructure/persistence:
• Relational database (SQLAlchemy or similar) under app/persistence/database/*
• Email adapter (SMTP or GCP email) in app/persistence/email/*
• File storage (GCS) in app/persistence/file_storage/*
• External clients: Google Calendar, Google Maps, OAuth2 client under app/client
• Configuration & secrets: app/config.py, environment variables, .env
• Test suite: tests/** for unit/integration coverage
• Deployment: Dockerfile, Makefile, Helm charts under deploy/helm, CI/CD workflows in .github/workflows
Main components and their interactions
a. HTTP Server (container):
• Receives HTTP requests → passes through Middleware (auth, headers, logging) → routes to Processor layer
b. Processor Layer:
• Each HTTP “processor” calls Domain logic (VOs, Enums, DTOs) and orchestrates Persistence/Client calls
c. Persistence Layer:
• Database adapter writes/reads domain entities → uses SQL models under app/persistence/database
• Email adapter sends verification/invitation emails
• File Storage adapter uploads/downloads avatars or other files to GCS
d. External Services:
• Google Calendar & Maps for location or scheduling data
• OAuth provider for user authentication
e. Data flow:
• Client → HTTP API → Domain service → Persistence/External client → Domain → HTTP Response → Client
Architectural patterns & design principles
• Layered architecture (Presentation → Application → Domain → Infrastructure)
• Dependency inversion: Domain interfaces are injected into processor/persistence modules
• Separation of concerns: Middleware handles cross‑cutting, clients handle external APIs, persistence handles storage
• Configuration via environment variables and app/config.py for 12‑factor compliance