# jmina117/convivencias_vivo_v2 architecture

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

- Interactive diagram: https://gitdiagram.com/jmina117/convivencias_vivo_v2
- Repository: https://github.com/jmina117/convivencias_vivo_v2

## Overview

##### Project type and purpose
- This is a full-stack web application named “Convivencia.”
- Backend: Django REST API (apps: authentication + convivencia + core + middleware).
- Frontend: Svelte/SvelteKit SPA (built with Vite).
- Data store: SQL Server accessed via ODBC.
- Deployment: Production behind Apache + Waitress, Development via Django runserver + Vite dev server.

##### File structure
- Top‐level dirs:
- convivencia_backend/ (Django project)
- frontend/ (SvelteKit application)
- config/ (Apache config, deployment scripts, systemd service)
- docs/ (deployment guide)
- Backend “convivencia_backend”:
- config/ (settings.py, database.py, ASGI/WSGI, URLs)
- authentication/ (models, admin, API serializers, views, permissions)
- convivencia/ (business logic API, models, serializers, views, custom queries, management commands)
- core/ (caching, debugging middleware, static views)
- middleware/ (CSRF, URL cleaning, reverse proxies)
- Frontend “frontend”:
- src/routes/ (page + layout components by feature)
- src/lib/ (reusable UI components, stores, utils, theming)
- vite.config.* (build vs SPA production)
- Deployment files:
- config/apache-prod.conf (Apache vhost + proxy rules)
- config/production/systemd/convivencia-backend.service
- PS1 scripts (setup, dev, prod, check).

##### README insights
- Dev workflow: `start.ps1 dev` runs Django on 5001 & Vite on 5174.
- Prod workflow: `start.ps1 prod` uses Waitress on 5001 behind Apache.
- Dependencies: Python 3.13, Node.js, SQL Server + ODBC Driver.

##### Main components
a. End User (Browser)
b. Apache HTTPD (Prod) / Vite Dev Server (Dev)—reverse proxy + static host
c. Django Application (Waitress/Wsgi or Runserver), with sub-components:
- URL Router & Middleware
- Apps: authentication, convivencia, core
- Management Commands
d. SQL Server (ODBC)
e. Frontend SPA (SvelteKit)
f. Optional: File system (static assets), Logging, Monitoring
g. Environment and Deployment Scripts (setup.ps1, systemd)

##### Relationships and data flows
- Browser → Apache (HTTP GET static files, proxy “/api/” to Django) → Django
- Dev: Browser → Vite Dev Server (hot reload) & API calls → Django runserver
- Django → ODBC Driver → SQL Server
- Django middleware (CSRF, URL cleaning, reverse proxy logic) intercept requests
- Frontend stores manage auth tokens and cache; calls backend via REST endpoints
- Management commands (e.g., cache_manage, setup_auth) invoked from CLI

##### Architectural patterns & design principles
- Layered architecture: Presentation (SPA) / Application (Django views/serializers) / Data (models/queries)
- Modular apps in Django following Django-app pattern
- Separation of concerns: authentication vs business logic
- Custom query manager pattern for chart data
- CLI management commands for operational tasks
- Dev vs Prod environments abstracted by PS1 scripts and config files

##### Essential elements to capture
- Clear labels on components (e.g., “Authentication API,” “Chart Queries”)
- Annotations for environment‐specific behavior (dev vs prod servers)
- External dependencies (SQL Server ODBC driver, Node.js)
- Related files/configs near their runtime component

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Entry
    Browser["End User<br/>(Browser)"]:::user

    %% Frontend Layer
    subgraph "Frontend"
        direction TB
        ViteDev["Vite Dev Server<br/>(port 5174)"]:::dev
        SvelteApp["SvelteKit SPA"]:::frontend
        StaticFiles["Built Static Files"]:::cdn
    end

    %% Backend Layer
    subgraph "Backend"
        direction TB
        subgraph "Production Environment"
            Apache["Apache HTTPD"]:::prod
            click Apache "https://github.com/jmina117/convivencias_vivo_v2/blob/main/config/apache-prod.conf"
            Waitress["Waitress / WSGI"]:::backend
            click Waitress "https://github.com/jmina117/convivencias_vivo_v2/blob/main/config/production/systemd/convivencia-backend.service"
        end
        subgraph "Development Environment"
            Runserver["Django runserver<br/>(port 5001)"]:::backend
        end

        %% Django Entry Points
        Router["URL Router<br/>(urls.py)"]:::backend
        click Router "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/config/urls.py"
        ASGI["ASGI Entry Point"]:::backend
        click ASGI "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/config/asgi.py"
        WSGI["WSGI Entry Point"]:::backend
        click WSGI "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/config/wsgi.py"
        DatabaseConfig["DB Config<br/>(ODBC)"]:::config
        click DatabaseConfig "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/config/database.py"

        %% Middleware
        Middleware["Global Middleware"]:::middleware
        click Middleware "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/middleware/api_csrf.py"
        click Middleware "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/middleware/clean_urls.py"
        click Middleware "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/middleware/reverse_proxy.py"

        %% Django Apps
        subgraph "Authentication App"
            AuthModels["Models"]:::component
            click AuthModels "https://github.com/jmina117/convivencias_vivo_v2/tree/main/convivencia_backend/authentication/models/"
            AuthSerializers["API Serializers"]:::component
            click AuthSerializers "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/authentication/api/serializers.py"
            AuthViews["API Views & URLs"]:::component
            click AuthViews "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/authentication/api/views.py"
            click AuthViews "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/authentication/api/urls.py"
            AuthAdmin["Admin"]:::component
            click AuthAdmin "https://github.com/jmina117/convivencias_vivo_v2/tree/main/convivencia_backend/authentication/admin/"
            SetupAuthCmd["setup_auth Cmd"]:::cmd
            click SetupAuthCmd "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/authentication/management/commands/setup_auth.py"
        end

        subgraph "Convivencia App"
            BillingAPI["Billing API"]:::component
            click BillingAPI "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/convivencia/api/billing_api.py"
            ChartsViews["Charts Views"]:::component
            click ChartsViews "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/convivencia/api/charts_views.py"
            ConvSerializers["API Serializers"]:::component
            click ConvSerializers "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/convivencia/api/serializers.py"
            CustomQueries["Custom Queries"]:::component
            click CustomQueries "https://github.com/jmina117/convivencias_vivo_v2/tree/main/convivencia_backend/convivencia/models/queries/"
            CacheManageCmd["cache_manage Cmd"]:::cmd
            click CacheManageCmd "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/convivencia/management/commands/cache_manage.py"
        end

        subgraph "Core App"
            CacheManager["Cache Manager"]:::component
            click CacheManager "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/core/cache_manager.py"
            DebugMiddleware["Debug Middleware"]:::component
            click DebugMiddleware "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/core/debug/middleware.py"
            StaticViews["Static Views"]:::component
            click StaticViews "https://github.com/jmina117/convivencias_vivo_v2/blob/main/convivencia_backend/core/static_views.py"
        end

        %% Database
        ODBC["ODBC Driver"]:::driver
        DB["SQL Server"]:::db

        %% Deployment Scripts & Configs
        Scripts["PS1 Scripts"]:::script
        click Scripts "https://github.com/jmina117/convivencias_vivo_v2/blob/main/start.ps1"
        click Scripts "https://github.com/jmina117/convivencias_vivo_v2/blob/main/dev.ps1"
        click Scripts "https://github.com/jmina117/convivencias_vivo_v2/blob/main/prod.ps1"
        click Scripts "https://github.com/jmina117/convivencias_vivo_v2/blob/main/setup.ps1"
        click Scripts "https://github.com/jmina117/convivencias_vivo_v2/blob/main/check.ps1"
        ProdSettings["Production Settings"]:::config
        click ProdSettings "https://github.com/jmina117/convivencias_vivo_v2/blob/main/config/settings_production.py"
    end

    %% Flows
    Browser -->|"HTTP 5174"| ViteDev
    Browser -->|"HTTP 80/443"| Apache
    Browser -->|"Static Assets"| StaticFiles
    ViteDev -->|"REST API"| Router
    SvelteApp -->|uses| ViteDev
    StaticFiles -->|served by| Apache

    Apache -->|"Proxy /api"| Waitress
    Runserver -->|"Direct API"| Router
    Waitress --> ASGI
    ASGI --> Router
    WSGI --> Router

    Router --> Middleware
    Middleware --> Router

    Router -->|"Auth Endpoints"| AuthViews
    AuthViews --> AuthSerializers --> AuthModels
    AuthViews --> AuthAdmin
    SetupAuthCmd -.-> AuthModels

    Router -->|"Convivencia Endpoints"| ChartsViews
    ChartsViews --> ConvSerializers --> CustomQueries --> DB
    BillingAPI --> ConvSerializers
    CacheManageCmd -.-> CacheManager
    CacheManager --> DB
    DebugMiddleware --> Router
    StaticViews --> StaticFiles

    Router --> DatabaseConfig --> ODBC --> DB

    Scripts -.-> Runserver
    Scripts -.-> Waitress
    Scripts -.-> Apache
    Scripts -.-> Middleware
    Scripts -.-> DatabaseConfig
    SystemdService["Systemd Service"]:::script
    click SystemdService "https://github.com/jmina117/convivencias_vivo_v2/blob/main/config/production/systemd/convivencia-backend.service"
    Scripts -.-> SystemdService

    ProdSettings --> Waitress
    ProdSettings --> Apache

    %% Styles
    classDef user fill:#f9f,stroke:#333,stroke-width:1px
    classDef frontend fill:#bbf,stroke:#333,stroke-width:1px
    classDef dev fill:#ddf,stroke:#333
    classDef prod fill:#cfc,stroke:#333
    classDef backend fill:#fbf,stroke:#333
    classDef middleware fill:#ffd,stroke:#333
    classDef component fill:#def,stroke:#333
    classDef cmd fill:#fdd,stroke:#333,dasharray: 5 5
    classDef db fill:#aff,stroke:#333,stroke-width:2px
    classDef driver fill:#faf,stroke:#333
    classDef script fill:#eee,stroke:#333,stroke-width:1px
    classDef config fill:#ffe,stroke:#333,stroke-dasharray: 2 2
    classDef cdn fill:#eef,stroke:#333,stroke-width:1px
```
