# setosystems/previanza architecture

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

- Interactive diagram: https://gitdiagram.com/setosystems/previanza
- Repository: https://github.com/setosystems/previanza

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“Sistema de Gestión de Seguros Previanza”) built with Flask (Python) for an insurance company’s end-to-end policy, client, agent, and report management.
- It uses Docker Compose to orchestrate four services: web (Flask/Gunicorn), db (PostgreSQL), nginx (reverse proxy), and redis (cache/sessions).

##### File Structure
- Top-level files:
- Dockerfile / docker-compose.yml / nginx.conf / docker-entrypoint.sh – container build & orchestration
- app.py / wsgi.py / gunicorn_config.py – Flask entrypoints
- config.py / extensions.py – application configuration & extension initialization
- models.py / migrations/ – SQLAlchemy models + Alembic migrations
- routes/ – Flask Blueprints for each module (auth, clients, policies, agents, products, reports, config)
- static/ + templates/ – frontend assets (Tailwind CSS, JS) & Jinja2 templates
- utils/ – helper modules (crypto, email, image handling, security, URL helpers)
- backup.sh, reset_db.py, update_product_images.py, worker.py – utilities & background jobs

##### README Insights
- Modules: auth, clients, policies, agents, reports, config
- Highlights use of sessions, email, CSRF, role-based access control

##### Main Components
a. Frontend Layer
- Browser (user) ←→ nginx (reverse proxy & static file server)
- Static assets: CSS (Tailwind) and JS served by nginx
- Jinja2 templates rendered by Flask
b. Backend Layer (Flask App)
- app.py → initializes Flask + Blueprints (routes/…)
- extensions: SQLAlchemy, Redis Session, Mail, WTForms, Security
- Worker (Celery or custom background scripts) for long-running tasks
c. Database Layer
- PostgreSQL (persistent storage for users, clients, policies, products, commissions)
- Alembic for schema migrations
d. Cache/Session Layer
- Redis for session storage & caching
e. External Services
- SMTP server for email notifications
- (Optional) File storage for uploads (local or S3)

##### Relationships and Data Flows
- User action in browser → HTTP request to nginx → forwarded to Gunicorn/Flask
- Flask authenticates via sessions in Redis, executes business logic, reads/writes to PostgreSQL
- Flask renders template + injects data → response back to browser via nginx
- Background jobs (worker.py) communicate with Flask context or directly with PostgreSQL/Redis
- Email flows: Flask → SMTP
- Migrations: developer/local CLI → Alembic → PostgreSQL

##### Architectural Patterns & Design Principles
- MVC-inspired:
- Models (models.py + migrations)
- Views (templates/)
- Controllers (routes/)
- Modular Blueprints for separation of concerns
- 12-factor app principles: config via environment, stateless services (sessions in Redis), logs to stdout
- Containerized micro-services (web, db, redis, nginx)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Browser["Browser"]:::frontend
    Browser -->|HTTP/HTTPS| Nginx

    %% Docker Compose Group
    subgraph "Docker Compose"
      direction TB
      Nginx["nginx (Reverse Proxy)"]:::frontend
      Web["Gunicorn + Flask App"]:::backend
      DB["PostgreSQL"]:::datastore
      Cache["Redis (Sessions/Cache)"]:::datastore
    end

    %% Web Container Internals
    subgraph "Web Container"
      direction TB
      AppPy["app.py"]:::backend
      WSGI["wsgi.py"]:::backend
      GunConfig["gunicorn_config.py"]:::backend
      Config["config.py"]:::backend
      Ext["extensions.py"]:::backend
      Models["models.py"]:::backend
      Alembic["alembic.ini"]:::backend
      Migrations["migrations/"]:::backend
      subgraph "Blueprints (routes/)"
        direction TB
        Auth["routes/auth.py"]:::backend
        Clients["routes/clients.py"]:::backend
        Policies["routes/policies.py"]:::backend
        Agents["routes/agents.py"]:::backend
        Products["routes/products.py"]:::backend
        Reports["routes/reports.py"]:::backend
        ConfigRoute["routes/config.py"]:::backend
      end
      subgraph "Views & Assets"
        direction TB
        Templates["templates/"]:::frontend
        StaticCSS["static/css/"]:::frontend
        StaticJS["static/js/"]:::frontend
        TailwindPy["compile_tailwind.py"]:::frontend
        TailwindConfig["tailwind.config.js"]:::frontend
      end
      subgraph "Utils & Jobs"
        direction TB
        Crypto["utils/crypto.py"]:::backend
        EmailUtil["utils/email.py"]:::backend
        ImgHandler["utils/image_handler.py"]:::backend
        SecurityUtil["utils/security.py"]:::backend
        URLHelpers["utils/url_helpers.py"]:::backend
        Worker["worker.py"]:::backend
        UpdateImgs["update_product_images.py"]:::backend
        ResetDB["reset_db.py"]:::backend
        Backup["backup.sh"]:::backend
      end
    end

    %% External Services
    SMTP["SMTP Server"]:::external
    FileStore["File Storage (S3/local)"]:::external
    InitSQL["init.sql"]:::backend
    Requirements["requirements.txt"]:::backend
    PackageJSON["package.json"]:::frontend

    %% Data Flows
    Nginx -->|"Proxy HTTP"| Web
    Web -->|"SQL queries"| DB
    Web -->|"Cache/Session"| Cache
    Web -->|"Send emails (SMTP)"| SMTP
    Web -->|"Store/Retrieve files"| FileStore
    Browser -->|Static files| Nginx

    %% Click Events
    click docker-compose.yml "https://github.com/setosystems/previanza/blob/previanza/docker-compose.yml"
    click Dockerfile "https://github.com/setosystems/previanza/tree/previanza/Dockerfile"
    click nginx.conf "https://github.com/setosystems/previanza/blob/previanza/nginx.conf"
    click docker-entrypoint.sh "https://github.com/setosystems/previanza/blob/previanza/docker-entrypoint.sh"
    click AppPy "https://github.com/setosystems/previanza/blob/previanza/app.py"
    click WSGI "https://github.com/setosystems/previanza/blob/previanza/wsgi.py"
    click GunConfig "https://github.com/setosystems/previanza/blob/previanza/gunicorn_config.py"
    click Config "https://github.com/setosystems/previanza/blob/previanza/config.py"
    click Ext "https://github.com/setosystems/previanza/blob/previanza/extensions.py"
    click Models "https://github.com/setosystems/previanza/blob/previanza/models.py"
    click Alembic "https://github.com/setosystems/previanza/blob/previanza/alembic.ini"
    click Migrations "https://github.com/setosystems/previanza/tree/previanza/migrations/"
    click Auth "https://github.com/setosystems/previanza/blob/previanza/routes/auth.py"
    click Clients "https://github.com/setosystems/previanza/blob/previanza/routes/clients.py"
    click Policies "https://github.com/setosystems/previanza/blob/previanza/routes/policies.py"
    click Agents "https://github.com/setosystems/previanza/blob/previanza/routes/agents.py"
    click Products "https://github.com/setosystems/previanza/blob/previanza/routes/products.py"
    click Reports "https://github.com/setosystems/previanza/blob/previanza/routes/reports.py"
    click ConfigRoute "https://github.com/setosystems/previanza/blob/previanza/routes/config.py"
    click Templates "https://github.com/setosystems/previanza/tree/previanza/templates/"
    click StaticCSS "https://github.com/setosystems/previanza/tree/previanza/static/css/"
    click StaticJS "https://github.com/setosystems/previanza/tree/previanza/static/js/"
    click TailwindPy "https://github.com/setosystems/previanza/blob/previanza/compile_tailwind.py"
    click TailwindConfig "https://github.com/setosystems/previanza/blob/previanza/tailwind.config.js"
    click Crypto "https://github.com/setosystems/previanza/blob/previanza/utils/crypto.py"
    click EmailUtil "https://github.com/setosystems/previanza/blob/previanza/utils/email.py"
    click ImgHandler "https://github.com/setosystems/previanza/blob/previanza/utils/image_handler.py"
    click SecurityUtil "https://github.com/setosystems/previanza/blob/previanza/utils/security.py"
    click URLHelpers "https://github.com/setosystems/previanza/blob/previanza/utils/url_helpers.py"
    click Worker "https://github.com/setosystems/previanza/blob/previanza/worker.py"
    click UpdateImgs "https://github.com/setosystems/previanza/blob/previanza/update_product_images.py"
    click ResetDB "https://github.com/setosystems/previanza/blob/previanza/reset_db.py"
    click Backup "https://github.com/setosystems/previanza/blob/previanza/backup.sh"
    click InitSQL "https://github.com/setosystems/previanza/blob/previanza/init.sql"
    click Requirements "https://github.com/setosystems/previanza/blob/previanza/requirements.txt"
    click PackageJSON "https://github.com/setosystems/previanza/blob/previanza/package.json"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#005B96,color:#005B96
    classDef backend fill:#E6FFE6,stroke:#28A745,color:#19692C
    classDef datastore fill:#FFE6CC,stroke:#E07B00,color:#A45C00
    classDef external fill:#F0F0F0,stroke:#888888,color:#555555
```
