# spectrumx/svi-code architecture

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

- Interactive diagram: https://gitdiagram.com/spectrumx/svi-code
- Repository: https://github.com/spectrumx/svi-code

## Overview

Based on our analysis of the file tree and the README, the SpectrumX Visualization Platform is a full-stack web application with a Django-based backend and a React-based frontend. In addition, the project leverages Docker Compose for orchestrating multiple services (for local development as well as production), has integrated Celery for background task processing, and uses modern authentication mechanisms (including Auth0 via django-allauth) for user login functionality.

##### Main Components
- Backend Server: Represented by the Django application (files in the “config”, “jobs”, “spectrumx_visualization_platform”, and “users” directories). This is where the core business logic lives, and it integrates with various modules (job processing, user management, API endpoints, etc.).
- Frontend Application: Found in the “frontend” directory. This is a React-based single-page application that handles user interaction, presentation of visualizations, and communicates with the backend.
- Task Processing: Celery workers, including beat for periodic tasks, are defined in various Docker Compose files and within the “config/celery_app.py” setup. This includes separate containers for workers, beat schedulers, and monitoring tools like Flower.
- Data Storage & Caching: PostgreSQL (with several dedicated maintenance scripts in the “compose/production/postgres” directory) is used as the primary relational database; Redis (located in the production compose structure) supports task queuing and caching.
- Reverse Proxy & Web Server: Nginx (and Traefik in production) serves as the web server and reverse proxy, managing HTTP requests for the frontend and backend.
- Jupyter Service: A service for Jupyter notebooks is provided (both in “compose/local/jupyter” and “compose/production/jupyter”), which likely supports interactive data visualization or analysis.
- External Integration: Auth0 integration for social authentication (via django-allauth) in the backend, indicated in the README modifications and environment settings.

##### Relationships and Interactions
- The Frontend sends API requests to the Django backend (the web server layer may further route requests using Nginx/Traefik).
- The Django backend interacts with PostgreSQL for persistent data storage and uses Redis in conjunction with Celery for asynchronous task processing.
- Celery workers operate asynchronously to run background tasks (e.g., processing jobs, generating visualizations) and interface with Django’s task definitions.
- Jupyter services and the Celery system may have interactions or provide insights via dashboards or notebooks.
- External users authenticate using Auth0, where the social login workflow is integrated into the backend.
- Docker Compose configurations segregate these components into containerized services, allowing for clear separation of runtime environments (local vs. production).

##### Architectural Patterns and Principles
- Full-Stack Separation: Clear decoupling of frontend (React) and backend (Django) allows independent scaling and maintenance.
- Microservices/Containerization: Use of Docker containers for different services (celery, postgres, redis, jupyter, nginx, etc.) reflects a microservices-inspired design.
- Asynchronous Processing: Celery is used to handle heavy or long-running tasks in the background.
- Modularization: Splitting the project into distinct Django apps (jobs, users, spx_vis) and frontend components (organized by pages and type) improves maintainability.

##### Relevant Technologies
- Django (Backend Framework)
- React (Frontend Framework)
- Celery (Asynchronous Task Processing)
- PostgreSQL and Redis (Data Storage & Caching)
- Docker/Docker Compose (Deployment & Environment Management)
- Nginx/Traefik (Reverse Proxy / Web Server)
- Auth0 and django-allauth (Authentication)
- Additional tools like Jupyter Notebooks for interactive analysis

##### Elements
- Annotations to represent architectural patterns (such as “API Layer”, “Asynchronous Task Handling”, “Containerized Deployment”) to facilitate understanding.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        ReactFrontend["React Frontend"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        DjangoBackend["Django Backend"]:::backend
        nodeConfig["Config"]:::backend
        nodeJobs["Jobs"]:::backend
        nodeSpectrum["SpectrumX App"]:::backend
        nodeUsers["Users"]:::backend
        DjangoBackend --> nodeConfig
        DjangoBackend --> nodeJobs
        DjangoBackend --> nodeSpectrum
        DjangoBackend --> nodeUsers
    end

    %% Task Processing
    subgraph "Task Processing"
        CeleryConfig["Celery Config"]:::celery
        LocalCelery["Local Celery"]:::celery
        LocalDjangoCelery["Local Django Celery"]:::celery
        ProductionDjangoCelery["Production Django Celery"]:::celery
        CeleryConfig --> LocalCelery
        CeleryConfig --> LocalDjangoCelery
        CeleryConfig --> ProductionDjangoCelery
    end

    %% Data Storage & Caching
    subgraph "Data Storage & Caching"
        Postgres["PostgreSQL"]:::database
        RedisNode["Redis"]:::database
    end

    %% Reverse Proxy & Web Server
    subgraph "Reverse Proxy & Web Server"
        LocalNginx["Local Nginx"]:::proxy
        ProductionNginx["Production Nginx"]:::proxy
        TraefikNode["Traefik"]:::proxy
    end

    %% Jupyter Service
    subgraph "Jupyter Service"
        LocalJupyter["Local Jupyter"]:::jupyter
        ProductionJupyter["Production Jupyter"]:::jupyter
    end

    %% External Integrations
    subgraph "External Integrations"
        AllAuthTemplates["Allauth Templates"]:::integration
        DjangoEnv[".envs/.local/.django"]:::integration
    end

    %% Connections
    ReactFrontend -->|"API"| DjangoBackend
    DjangoBackend -->|"Queries"| Postgres
    DjangoBackend -->|"CacheQueue"| RedisNode
    DjangoBackend -->|"TaskCalls"| CeleryConfig
    DjangoBackend -->|"Auth"| AllAuthTemplates
    DjangoBackend -->|"Auth"| DjangoEnv
    DjangoBackend -->|"Dashboard"| LocalJupyter
    DjangoBackend -->|"Dashboard"| ProductionJupyter
    CeleryConfig -->|"Queue"| RedisNode
    LocalNginx -->|"Routes"| ReactFrontend
    LocalNginx -->|"Routes"| DjangoBackend
    ProductionNginx -->|"Routes"| ReactFrontend
    ProductionNginx -->|"Routes"| DjangoBackend
    TraefikNode -->|"Routes"| DjangoBackend
    TraefikNode -->|"Routes"| ReactFrontend

    %% Click Events
    click nodeConfig "https://github.com/spectrumx/svi-code/tree/master/config"
    click nodeJobs "https://github.com/spectrumx/svi-code/tree/master/jobs"
    click nodeSpectrum "https://github.com/spectrumx/svi-code/tree/master/spectrumx_visualization_platform"
    click nodeUsers "https://github.com/spectrumx/svi-code/tree/master/users"
    click ReactFrontend "https://github.com/spectrumx/svi-code/tree/master/frontend"
    click CeleryConfig "https://github.com/spectrumx/svi-code/blob/master/config/celery_app.py"
    click LocalCelery "https://github.com/spectrumx/svi-code/tree/master/compose/local/celery"
    click LocalDjangoCelery "https://github.com/spectrumx/svi-code/tree/master/compose/local/django/celery"
    click ProductionDjangoCelery "https://github.com/spectrumx/svi-code/tree/master/compose/production/django/celery"
    click Postgres "https://github.com/spectrumx/svi-code/tree/master/compose/production/postgres"
    click RedisNode "https://github.com/spectrumx/svi-code/tree/master/compose/production/redis"
    click LocalNginx "https://github.com/spectrumx/svi-code/tree/master/compose/local/nginx"
    click ProductionNginx "https://github.com/spectrumx/svi-code/tree/master/compose/production/nginx"
    click TraefikNode "https://github.com/spectrumx/svi-code/tree/master/compose/production/traefik"
    click LocalJupyter "https://github.com/spectrumx/svi-code/tree/master/compose/local/jupyter"
    click ProductionJupyter "https://github.com/spectrumx/svi-code/tree/master/compose/production/jupyter"
    click AllAuthTemplates "https://github.com/spectrumx/svi-code/tree/master/spectrumx_visualization_platform/templates/allauth"
    click DjangoEnv "https://github.com/spectrumx/svi-code/blob/master/.envs/.local/.django"

    %% Styles
    classDef frontend fill:#a8e6cf,stroke:#333,stroke-width:2px;
    classDef backend fill:#80d4ff,stroke:#333,stroke-width:2px;
    classDef celery fill:#fff3b0,stroke:#333,stroke-width:2px;
    classDef database fill:#ffaaa5,stroke:#333,stroke-width:2px;
    classDef proxy fill:#d3c0eb,stroke:#333,stroke-width:2px;
    classDef jupyter fill:#caffbf,stroke:#333,stroke-width:2px;
    classDef integration fill:#ffdfba,stroke:#333,stroke-width:2px;

    class ReactFrontend frontend;
    class DjangoBackend,nodeConfig,nodeJobs,nodeSpectrum,nodeUsers backend;
    class CeleryConfig,LocalCelery,LocalDjangoCelery,ProductionDjangoCelery celery;
    class Postgres,RedisNode database;
    class LocalNginx,ProductionNginx,TraefikNode proxy;
    class LocalJupyter,ProductionJupyter jupyter;
    class AllAuthTemplates,DjangoEnv integration;
```
