# tinocoalexander/surveyanalytics architecture

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

- Interactive diagram: https://gitdiagram.com/tinocoalexander/surveyanalytics
- Repository: https://github.com/tinocoalexander/surveyanalytics

## Overview

##### Project type and purpose
- This is a monolithic, full-stack Django web application named SurveyAnalytics.
- Purpose: allow authenticated users to upload survey response files (CSV/XLS/XLSX), process them with Pandas, generate charts via Matplotlib, display insights in HTML, and produce downloadable PDF reports via WeasyPrint.

##### File structure
- Top level:
- manage.py and survey_analytics/ (Django project settings, ASGI/WSGI, global URLs)
- apps: analysis/, users/, errors/
- static/ (CSS, JS, images)
- media/ (uploaded survey files)
- Each app follows Django’s MVC: models.py, views.py, urls.py, templates/, migrations/.
- Configuration: settings.py uses python-decouple for env vars; static and media roots defined; error app for custom HTTP error pages.

##### README insights
- Tech stack: Django 5.1.5, Python 3.12, Pandas, Matplotlib, WeasyPrint, python-decouple, django-widget-tweaks.
- Workflow: User → login/register → upload survey → Pandas analysis + Matplotlib charts → render in HTML + PDF via WeasyPrint → CRUD (list/delete) surveys.
- Deployment: production uses Gunicorn/uWSGI + Nginx, environment variables, ALLOWED_HOSTS, static/media handling.

##### Main components and interactions
a. Components
1. Client (Browser)
2. Static Asset Server (via Django or Nginx/CDN)
3. Django Web Server (Gunicorn/uWSGI)
- URL Router
- Users App (authentication, email via SMTP)
- Analysis App (file upload, data pipeline, chart generation, PDF generation)
- Errors App (custom 400/401/404 pages)
4. Database (e.g., PostgreSQL or SQLite)
5. File Storage (media/ directory for uploaded surveys)
6. External Services
- SMTP Email Server (activate accounts, password reset)
- WeasyPrint (renders HTML → PDF)
- Matplotlib (generates .png images of charts)
7. Environment Variables Provider (python-decouple/.env)
b. Relationships & data flows
- Browser → HTTP(S) → Django Web Server
- Django → ORM → Database
- File upload: Browser → Django → save file → media storage
- Analysis pipeline: Django reads file from media → Pandas processes → Matplotlib outputs chart images → templates embed charts + insights
- PDF report: HTML template → WeasyPrint → PDF delivered to Browser
- SMTP: Django Users App → SMTP credentials → send activation/reset emails
- Static files: Browser fetches CSS/JS/images from static server
c. Architectural patterns & principles
- Monolithic MVC: separation of concerns between models, views, templates
- Three Django apps = modular structure (authentication, business logic, error handling)
- Single codebase deploys to one web server process; static assets can be offloaded to CDN
- Data pipeline stage: file ingestion → processing → visualization → reporting
d. Key technologies
- Django (request routing, ORM, templating)
- Pandas (data manipulation)
- Matplotlib (chart rendering)
- WeasyPrint (HTML-to-PDF)
- python-decouple (config management)
- django-widget-tweaks (form rendering)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Tier
    subgraph "Client Tier" 
        direction TB
        Browser["Browser"]:::front
        StaticServer["Static Asset Server<br/>(CSS, JS, Images)"]:::front
    end

    %% Server Tier
    subgraph "Server Tier"
        direction TB

        %% Environment
        Env["Environment Variables<br/>(python-decouple)"]:::infra

        %% Django Entry Points & Config
        subgraph "Django Project" 
            direction TB
            Manage["manage.py"]:::backend
            Settings["settings.py"]:::backend
            URLRouter["urls.py"]:::backend
            ASGI["asgi.py"]:::backend
            WSGI["wsgi.py"]:::backend
        end

        %% Apps
        subgraph "Users App" 
            direction TB
            UModels["models.py"]:::backend
            UForms["forms.py / decorators.py"]:::backend
            UViews["views.py"]:::backend
            UURLs["urls.py"]:::backend
            UTemplates["templates/ users & emails"]:::front
        end

        subgraph "Analysis App"
            direction TB
            AModels["models.py"]:::backend
            AViews["views.py"]:::backend
            AURLs["urls.py"]:::backend
            ATemplates["templates/ analysis"]:::front
            Pandas["Pandas"]:::backend
            Matplotlib["Matplotlib"]:::backend
            Weasy["WeasyPrint"]:::backend
        end

        subgraph "Errors App"
            direction TB
            EModels["migrations"]:::backend
            EViews["views.py"]:::backend
            EURLs["urls.py"]:::backend
            ETemplates["templates/ errors"]:::front
        end

        %% Infrastructure
        DB[(Database)]:::infra
        Media["media/ directory<br/>(Uploaded files)"]:::infra
        SMTP["SMTP Email Server"]:::infra
    end

    %% Data Flows
    Browser -->|"HTTP(S) GET/POST"| URLRouter
    Browser -->|"Fetch static assets"| StaticServer
    URLRouter --> UURLs
    URLRouter --> AURLs
    URLRouter --> EURLs

    UURLs --> UViews
    UViews --> UModels
    UViews -->|"ORM query"| DB
    UViews -->|"send email"| SMTP

    AURLs --> AViews
    Browser -->|"POST /upload"| AViews
    AViews -->|"save file"| Media
    AViews --> Pandas
    Pandas --> Matplotlib
    Matplotlib --> ATemplates
    ATemplates --> Weasy
    Weasy -->|"PDF"| Browser
    AViews -->|"ORM query"| DB

    EURLs --> EViews
    EViews --> ETemplates

    Env --> Settings
    Settings --> URLRouter
    Settings --> StaticServer
    Settings --> Media
    Settings --> DB
    Settings --> SMTP

    %% Click Events
    click Manage "https://github.com/tinocoalexander/surveyanalytics/blob/main/survey_analytics/manage.py"
    click Settings "https://github.com/tinocoalexander/surveyanalytics/blob/main/survey_analytics/survey_analytics/settings.py"
    click URLRouter "https://github.com/tinocoalexander/surveyanalytics/blob/main/survey_analytics/survey_analytics/urls.py"
    click ASGI "https://github.com/tinocoalexander/surveyanalytics/blob/main/survey_analytics/survey_analytics/asgi.py"
    click WSGI "https://github.com/tinocoalexander/surveyanalytics/blob/main/survey_analytics/survey_analytics/wsgi.py"
    click UURLs "https://github.com/tinocoalexander/surveyanalytics/blob/main/survey_analytics/users/urls.py"
    click UViews "https://github.com/tinocoalexander/surveyanalytics/blob/main/survey_analytics/users/views.py"
    click UModels "https://github.com/tinocoalexander/surveyanalytics/blob/main/survey_analytics/users/models.py"
    click UForms "https://github.com/tinocoalexander/surveyanalytics/blob/main/survey_analytics/users/forms.py"
    click UTemplates "https://github.com/tinocoalexander/surveyanalytics/tree/main/survey_analytics/users/templates/users/"
    click AURLs "https://github.com/tinocoalexander/surveyanalytics/blob/main/survey_analytics/analysis/urls.py"
    click AViews "https://github.com/tinocoalexander/surveyanalytics/blob/main/survey_analytics/analysis/views.py"
    click AModels "https://github.com/tinocoalexander/surveyanalytics/blob/main/survey_analytics/analysis/models.py"
    click ATemplates "https://github.com/tinocoalexander/surveyanalytics/tree/main/survey_analytics/analysis/templates/analysis/"
    click EURLs "https://github.com/tinocoalexander/surveyanalytics/blob/main/survey_analytics/errors/urls.py"
    click EViews "https://github.com/tinocoalexander/surveyanalytics/blob/main/survey_analytics/errors/views.py"
    click ETemplates "https://github.com/tinocoalexander/surveyanalytics/tree/main/survey_analytics/errors/templates/errors/"
    click Media "https://github.com/tinocoalexander/surveyanalytics/tree/main/survey_analytics/media/"
    click StaticServer "https://github.com/tinocoalexander/surveyanalytics/tree/main/survey_analytics/static/"

    %% Styles
    classDef front fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef infra fill:#fff3cd,stroke:#856404,color:#856404;
```
