# natea/socialcal architecture

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

- Interactive diagram: https://gitdiagram.com/natea/socialcal
- Repository: https://github.com/natea/socialcal

## Overview

##### Project type and purpose
- SocialCal is a full-stack, monolithic Django web application.
- Its core purpose is to scrape event data from various websites (and optionally enrich it via external APIs like Spotify or OpenAI), store it in a database, and expose those events to end users through both a web UI and a REST API.

##### File structure for architectural cues
- Top-level Django project (“socialcal”) with settings split by environment (base, development, production, test).
- Multiple Django apps under the project root:
– accounts (user account management + adapters)
– users (straightforward user model + admin)
– profiles (user profiles & preferences)
– events (scrapers, models, tasks, management commands)
– calendar_app (calendar view rendering)
– api (DRF serializers, views, URLs)
– core (home page, privacy/terms-of-service)
- Static assets in “static” and built/admin assets in “staticfiles.”
- Asynchronous tasks likely via Django-Celery or management commands (`events/tasks.py`, `events/management/commands`).
- Configuration files: Dockerfile, docker-entrypoint.sh, .env-dummy, render.yaml for deployment.
- Testing scaffolding: pytest, conftest.py, per-app tests.

##### Confirm technical stack and runtime behavior from README
- Python 3 + Django + Django REST Framework
- External integrations: OPENAI_API_KEY, SPOTIFY_CLIENT_ID / SECRET
- Single RDBMS (e.g., Postgres) behind Django ORM
- Webserver via `manage.py runserver` (development), containerized/WSGI in production

##### Main components
a. Client layer
– Web browser (user UI)
– Optional external clients consuming REST API (mobile apps, calendar apps)
b. Web tier
– NGINX (or similar) reverse proxy / Load Balancer
– WSGI server (Gunicorn / uWSGI) running Django
c. Django monolith
– URL Dispatcher → Django apps:
- accounts & users (auth, signup, login)
- profiles (profile CRUD, calendar visibility)
- events (scrapers, event model, tasks)
- calendar_app (month/day views, ICS generation)
- api (DRF endpoints for events, profiles)
- core (static pages)
– Settings module (base + env-specific overrides)
d. Background worker tier
– Celery worker / Django management commands
- Periodic or on-demand scrapers (crawl4ai, ical, site scrapers)
- Spotify enrichment, ICS generation tasks
e. Data tier
– Relational database (PostgreSQL or other)
– Static file storage (S3 or local FS for staticfiles/media)
f. External services
– Event source websites (HTTP scrapes)
– Spotify API
– OpenAI API (optional curation)

##### Relationships and data flows
- User → HTTP → NGINX → Gunicorn → Django URL router → views → ORM → Database → views → HTTP → User
- Django views / APIs may trigger Celery tasks or run scrapers via management commands
- Celery worker → scrapes external sites / calls Spotify or OpenAI → writes events to Database
- API clients consume serialized event data from DRF endpoints
- Calendar ICS feeds generated on-the-fly by calendar_app and served to clients

##### Architectural patterns and design principles
- Monolithic modularization (each Django app encapsulates a feature set)
- Layered architecture: Presentation (templates + JS) / Business logic (views, tasks) / Data (models, DB)
- Asynchronous processing of long-running jobs via Celery or Django commands
- Clear separation of concerns:
– “api” app for machine-readable interfaces
– “calendar_app” & templates for human-readable UI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Browser["Web Browser"]:::frontend
    APIClient["External API Client"]:::frontend

    %% Web Tier
    NGINX["NGINX Reverse Proxy"]:::backend
    Gunicorn["Gunicorn WSGI Server"]:::backend

    %% Django Application
    subgraph "Django Monolith"
        direction TB
        URLDispatcher["URL Dispatcher\n(socialcal/urls.py)"]:::backend
        click URLDispatcher "https://github.com/natea/socialcal/blob/main/socialcal/urls.py"

        WSGI["WSGI Entry Point\n(socialcal/wsgi.py)"]:::backend
        click WSGI "https://github.com/natea/socialcal/blob/main/socialcal/wsgi.py"

        subgraph "Settings Module"
            direction TB
            SettingsBase["base.py"]:::backend
            SettingsDev["development.py"]:::backend
            SettingsProd["production.py"]:::backend
            SettingsTest["test.py"]:::backend
            click SettingsBase "https://github.com/natea/socialcal/blob/main/socialcal/settings/base.py"
            click SettingsDev "https://github.com/natea/socialcal/blob/main/socialcal/settings/development.py"
            click SettingsProd "https://github.com/natea/socialcal/blob/main/socialcal/settings/production.py"
            click SettingsTest "https://github.com/natea/socialcal/blob/main/socialcal/settings/test.py"
        end

        subgraph "Accounts App" 
            direction TB
            AccountsDir["accounts/"]:::backend
            click AccountsDir "https://github.com/natea/socialcal/tree/main/accounts/"
            Adapters["adapters.py"]:::backend
            click Adapters "https://github.com/natea/socialcal/blob/main/accounts/adapters.py"
            AccountsConfig["apps.py"]:::backend
            click AccountsConfig "https://github.com/natea/socialcal/blob/main/accounts/apps.py"
        end

        subgraph "Users App"
            direction TB
            UsersDir["users/"]:::backend
            click UsersDir "https://github.com/natea/socialcal/tree/main/users/"
            UserModel["models.py"]:::backend
            click UserModel "https://github.com/natea/socialcal/blob/main/users/models.py"
            UserAdmin["admin.py"]:::backend
            click UserAdmin "https://github.com/natea/socialcal/blob/main/users/admin.py"
        end

        subgraph "Profiles App"
            direction TB
            ProfilesDir["profiles/"]:::backend
            click ProfilesDir "https://github.com/natea/socialcal/tree/main/profiles/"
            ProfileModel["models.py"]:::backend
            click ProfileModel "https://github.com/natea/socialcal/blob/main/profiles/models.py"
        end

        subgraph "Events App"
            direction TB
            EventsDir["events/"]:::backend
            click EventsDir "https://github.com/natea/socialcal/tree/main/events/"
            EventModels["models.py"]:::backend
            click EventModels "https://github.com/natea/socialcal/blob/main/events/models.py"
            EventScrapers["scrapers/"]:::backend
            click EventScrapers "https://github.com/natea/socialcal/tree/main/events/scrapers/"
            EventTasks["tasks.py"]:::worker
            click EventTasks "https://github.com/natea/socialcal/blob/main/events/tasks.py"
        end

        subgraph "Calendar App"
            direction TB
            CalendarDir["calendar_app/"]:::backend
            click CalendarDir "https://github.com/natea/socialcal/tree/main/calendar_app/"
            CalendarViews["views.py"]:::backend
            click CalendarViews "https://github.com/natea/socialcal/blob/main/calendar_app/views.py"
        end

        subgraph "API App"
            direction TB
            APIDir["api/"]:::backend
            click APIDir "https://github.com/natea/socialcal/tree/main/api/"
            APISerializers["serializers.py"]:::backend
            click APISerializers "https://github.com/natea/socialcal/blob/main/api/serializers.py"
            APIViews["views.py"]:::backend
            click APIViews "https://github.com/natea/socialcal/blob/main/api/views.py"
        end

        subgraph "Core App"
            direction TB
            CoreDir["core/"]:::backend
            click CoreDir "https://github.com/natea/socialcal/tree/main/core/"
            CoreViews["views.py"]:::backend
            click CoreViews "https://github.com/natea/socialcal/blob/main/core/views.py"
        end

        URLDispatcher --> AccountsDir
        URLDispatcher --> UsersDir
        URLDispatcher --> ProfilesDir
        URLDispatcher --> EventsDir
        URLDispatcher --> CalendarDir
        URLDispatcher --> APIDir
        URLDispatcher --> CoreDir
    end

    %% Worker Tier
    subgraph "Background Workers"
        direction TB
        CeleryWorker["Celery Worker"]:::worker
        click CeleryWorker "https://github.com/natea/socialcal/blob/main/events/tasks.py"
    end

    %% Data Tier
    DB["PostgreSQL Database"]:::data
    StaticStorage["Static & Media Storage"]:::data

    %% External Services
    EventSites["Event Source Websites"]:::external
    SpotifyAPI["Spotify API"]:::external
    OpenAIAPI["OpenAI API"]:::external

    %% Flows
    Browser -->|"HTTP Request"| NGINX
    APIClient -->|"HTTP Request"| NGINX
    NGINX -->|"WSGI"| Gunicorn
    Gunicorn -->|"Route Request"| URLDispatcher

    URLDispatcher -->|"ORM Query"| DB
    DB -->|"Response Data"| URLDispatcher
    URLDispatcher -->|"Render Templates / JSON"| Gunicorn
    Gunicorn -->|"HTTP Response"| NGINX
    NGINX -->|"HTTP Response"| Browser
    NGINX -->|"HTTP Response"| APIClient

    URLDispatcher -->|"Trigger Task"| CeleryWorker
    CeleryWorker -->|"Scrape/Crawl"| EventSites
    CeleryWorker -->|"Enrich"| SpotifyAPI
    CeleryWorker -->|"Enrich"| OpenAIAPI
    CeleryWorker -->|"DB Write"| DB

    CalendarDir -->|"Generate ICS"| DB
    CalendarDir -->|"Stream ICS"| Browser

    StaticStorage -->|"Serve Static Files"| Browser

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#357ABD,color:#000
    classDef backend fill:#D5F5E3,stroke:#27AE60,color:#000
    classDef worker fill:#FDEBD0,stroke:#E67E22,color:#000
    classDef data fill:#FCF3CF,stroke:#F1C40F,color:#000
    classDef external fill:#F5EEF8,stroke:#8E44AD,color:#000
```
