# joinee-im/backend architecture

> Architecture diagram of the GitHub repository joinee-im/backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joinee-im/backend
- Repository: https://github.com/joinee-im/backend

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client"]:::external

    %% Server and Layers
    subgraph "FastAPI / Uvicorn HTTP Server"
        Main["FastAPI Server\n(app/main.py)"]:::api
        subgraph "Middleware"
            Auth["Auth Middleware"]:::api
            Headers["Header Management"]:::api
            Logging["Request/Response Logging"]:::api
        end
        Processor["Processor Layer\n(app/processor/http)"]:::api
        subgraph "Domain & Business Logic"
            Base["Core Models, Enums, VOs, Use‑cases\n(app/base)"]:::domain
            Utils["Utilities (context, security, invitation, parsing)\n(app/utils)"]:::domain
        end
    end

    %% Persistence
    subgraph "Persistence Layer"
        DB["PostgreSQL DB Adapter\n(app/persistence/database)"]:::persistence
        Email["Email Service Adapter\n(app/persistence/email)"]:::persistence
        File["GCS File Storage Adapter\n(app/persistence/file_storage)"]:::persistence
    end

    %% External Services
    subgraph "External Services"
        Cal["Google Calendar API"]:::external
        Maps["Google Maps API"]:::external
        OAuth["OAuth2 Provider"]:::external
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & DevOps"
        Config["Configuration & Secrets\n(app/config.py, .env.example)"]:::infra
        Docker["Dockerfile & Makefile"]:::infra
        Chart["Helm Charts\n(deploy/helm/charts)"]:::infra
        CI["CI/CD Workflows\n(.github/workflows)"]:::infra
    end

    %% Data Flow
    Client --> Main
    Main --> Auth --> Headers --> Logging --> Processor
    Processor --> Base
    Processor --> Utils
    Processor --> DB
    Processor --> Email
    Processor --> File
    Processor --> Cal
    Processor --> Maps
    Processor --> OAuth

    %% Infrastructure Connections
    Config --> Main
    Docker --> Main
    Chart --> Main
    CI --> Docker
    CI --> Chart

    %% Click Events
    click Main "https://github.com/joinee-im/backend/blob/master/app/main.py"
    click Processor "https://github.com/joinee-im/backend/tree/master/app/processor/http/"
    click Auth "https://github.com/joinee-im/backend/blob/master/app/middleware/auth.py"
    click Headers "https://github.com/joinee-im/backend/blob/master/app/middleware/headers.py"
    click Logging "https://github.com/joinee-im/backend/blob/master/app/middleware/logging.py"
    click Base "https://github.com/joinee-im/backend/tree/master/app/base/"
    click Utils "https://github.com/joinee-im/backend/tree/master/app/utils/"
    click DB "https://github.com/joinee-im/backend/tree/master/app/persistence/database/"
    click Email "https://github.com/joinee-im/backend/tree/master/app/persistence/email/"
    click File "https://github.com/joinee-im/backend/tree/master/app/persistence/file_storage/"
    click Cal "https://github.com/joinee-im/backend/blob/master/app/client/google_calendar.py"
    click Maps "https://github.com/joinee-im/backend/blob/master/app/client/google_maps.py"
    click OAuth "https://github.com/joinee-im/backend/blob/master/app/client/oauth.py"
    click Config "https://github.com/joinee-im/backend/blob/master/app/config.py"
    click Docker "https://github.com/joinee-im/backend/tree/master/Dockerfile"
    click Chart "https://github.com/joinee-im/backend/tree/master/deploy/helm/charts/"
    click CI "https://github.com/joinee-im/backend/blob/master/.github/workflows/ci.yml"

    %% Styles
    classDef api fill:#D0E7FF,stroke:#333,stroke-width:1px
    classDef domain fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef persistence fill:#FFE0B3,stroke:#333,stroke-width:1px
    classDef external fill:#E6E0FF,stroke:#333,stroke-width:1px
    classDef infra fill:#E0E0E0,stroke:#333,stroke-width:1px
```
