# fmgarciaa/cride architecture

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

- Interactive diagram: https://gitdiagram.com/fmgarciaa/cride
- Repository: https://github.com/fmgarciaa/cride

## Overview

##### Project type and purpose
- This is a backend-only, containerized Django REST Framework application called CRide—a carpooling service API.
- It exposes HTTP endpoints for managing users, ride requests, rides, circles, invitations and ratings.
- It offloads asynchronous tasks (email verification, notifications) to Celery and uses Docker Compose for local and production orchestration.

##### File structure
- Top-level “compose” directories define two Docker Compose stacks:
– compose/local (Django app, Celery worker/beat/flower, Postgres, Redis, etc.)
– compose/production (adds Caddy reverse-proxy, production-grade Postgres maintenance scripts, optimized Django image).
- “config” hosts Django settings split by environment (base, local, production, test), URL routing (urls.py) and WSGI entrypoint.
- “cride” folder contains Django apps:
– users (models, serializers, views),
– circles (models, permissions, invitations),
– rides (models, serializers, views, ratings),
– taskapp (Celery configuration and tasks),
– templates for emails.
- Requirements and environment files for 12-factor config via django-environ.

##### README for technical stack
- Python 3.6-alpine, Django 3.2, DRF
- Docker Compose
- Celery with Redis as broker and cache
- Flower for Celery monitoring
- Caddy as HTTP reverse proxy
- PostgreSQL as the primary datastore
- Anymail for email delivery (Mailgun/AWS SES)
- S3/Google Cloud/Azure for media storage

##### Main components
- API Gateway / Reverse Proxy: Caddy server receiving external HTTP(S) traffic
- Web/API App: Gunicorn + Django (config/wsgi.py) running the REST API
- Database: PostgreSQL (main data persistence)
- Cache and Message Broker: Redis (caching layer, Celery broker)
- Asynchronous Workers: Celery worker and Celery Beat scheduler
- Monitoring: Celery Flower UI
- External Services:
– Object Storage (S3 or equivalent) for media
– Email Provider (Mailgun or SES) via Anymail
- Local development stack vs. production differ only by image choices and added maintenance tasks for Postgres.

##### Relationships and data flow
- Clients (mobile/web) → HTTP(S) → Caddy → Django/Gunicorn
- Django (sync) ↔ PostgreSQL
- Django (cache lookups, locks) ↔ Redis
- Django (enqueue tasks) → Redis broker → Celery Worker
- Celery Beat → schedules periodic Celery tasks
- Celery Worker → executes tasks (e.g., send email via Anymail → Email Provider; process image uploads → S3)
- Flower → monitors Celery Worker
- All containers communicate over an internal Docker network; config files define service dependencies.

##### Architectural patterns and design principles
- Monolithic Django service with multiple Django “apps” representing bounded contexts (users, rides, circles).
- Asynchronous task pattern via Celery.
- 12-factor app for environment configuration, backing services (DB, cache, broker), build and release separation.
- Separation of concerns: HTTP layer (Caddy, Gunicorn), application logic (Django views/serializers), data layer (ORM), background layer (Celery).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client[/"Mobile/Web Clients"/]:::external

    %% Gateway
    Client -->|"HTTPS"| Caddy["Caddy Reverse Proxy"]:::gateway

    %% Application Layer
    Caddy -->|"HTTP"| Django["Django + Gunicorn"]:::app

    subgraph "Django Service"
        direction TB
        Django
        subgraph "Django Apps"
            direction TB
            Users["Users App"]:::appModule
            Circles["Circles App"]:::appModule
            Rides["Rides App"]:::appModule
            TaskApp["TaskApp (Celery Config)"]:::appModule
        end
    end

    %% Data Stores
    Django -->|"ORM (PSQL)"| Postgres[(PostgreSQL)]:::db
    Django -->|"Cache|Broker (Redis-py)"| Redis[(Redis)]:::cache

    %% Asynchronous Processing
    Django -->|"Enqueue Task (AMQP)"| BrokerRedis[(Redis Broker)]:::broker
    BrokerRedis -->|"AMQP"| CeleryWorker["Celery Worker"]:::worker
    CeleryBeat["Celery Beat Scheduler"]:::worker
    CeleryBeat -->|"Schedules Tasks"| BrokerRedis

    %% External Integrations
    CeleryWorker -->|"Send Email (SMTP/HTTP)"| Email["Email Provider"]:::external
    CeleryWorker -->|"Upload Media (S3 API)"| Storage[(Object Storage)]:::datastore

    %% Monitoring
    BrokerRedis --> Flower["Flower UI"]:::monitor
    CeleryWorker --> Flower

    %% Click Events
    click Caddy "https://github.com/fmgarciaa/cride/tree/main/compose/production/caddy/Caddyfile"
    click Django "https://github.com/fmgarciaa/cride/blob/main/config/wsgi.py"
    click Django "https://github.com/fmgarciaa/cride/blob/main/manage.py"
    click Users "https://github.com/fmgarciaa/cride/blob/main/cride/users/models/users.py"
    click Circles "https://github.com/fmgarciaa/cride/blob/main/cride/circles/models/circles.py"
    click Rides "https://github.com/fmgarciaa/cride/blob/main/cride/rides/models/rides.py"
    click TaskApp "https://github.com/fmgarciaa/cride/blob/main/cride/taskapp/celery.py"
    click Postgres "https://github.com/fmgarciaa/cride/tree/main/compose/production/postgres/Dockerfile"
    click CeleryWorker "https://github.com/fmgarciaa/cride/tree/main/compose/local/django/celery/worker/start"
    click CeleryBeat "https://github.com/fmgarciaa/cride/tree/main/compose/local/django/celery/beat/start"
    click Flower "https://github.com/fmgarciaa/cride/tree/main/compose/local/django/celery/flower/start"
    click Email "https://github.com/fmgarciaa/cride/blob/main/cride/templates/email/users/account_verification.html"

    %% Styles
    classDef gateway fill:#FFD700,stroke:#333,stroke-width:1px
    classDef app fill:#ADFF2F,stroke:#333,stroke-width:1px
    classDef appModule fill:#98FB98,stroke:#333,stroke-width:1px
    classDef db fill:#FFB347,stroke:#333,stroke-width:1px
    classDef cache fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef broker fill:#40E0D0,stroke:#333,stroke-width:1px
    classDef worker fill:#FF69B4,stroke:#333,stroke-width:1px
    classDef datastore fill:#FFFACD,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef monitor fill:#E6E6FA,stroke:#333,stroke-width:1px
```
