# aix-group/webcards architecture

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

- Interactive diagram: https://gitdiagram.com/aix-group/webcards
- Repository: https://github.com/aix-group/webcards

## Overview

##### Project type and purpose
- This is a full-stack Django web application (“WEBCARDS”) whose primary function is to let users upload ML models, datasets, and metadata, then generate HTML “model cards” and data sheets to support FEAT (Fairness, Ethics, Accountability, Transparency) principles.
- Key features (from README and file tree):
- Two Django apps: mc_and_datasheet (core UI, upload handling, generation) and cleanup_sessions (session/file cleanup).
- Uses Django templating plus static assets (CSS/JS) for the frontend.
- Leverages Google’s Model Card Toolkit and a custom library (featai_lib) to build cards.
- Stores uploads in media/uploads, sessions via cookies, metadata in SQLite3.
- CI/CD via GitHub Actions builds/tests a Docker image and pushes to DockerHub.

##### File structure
- Top‐level files: manage.py, Dockerfile, .github/workflows (CI), requirements.txt, docs/, templates/, utils/, test_input/, db.sqlite3.zip.
- Core Django project: mysite/ (settings.py, urls.py, wsgi.py, asgi.py) + two apps:
- mc_and_datasheet/: handles forms, views, models, templates, static/ (CSS, JS, admin overrides).
- cleanup_sessions/: implements a management command for cleaning old media uploads.
- Utility code: utils/model_card_lib_v2.py, utils/datasheet.py, plus a packaged wheel.
- Documentation in docs/source.
- Test fixtures in test_input/.

##### README for additional insights
- Confirms use of Django and SQLite3.
- Mentions temporary file storage in media/uploads keyed by session cookie; automatic removal after 1 hour.
- CI/CD pipeline ensures tests pass, Docker image built/published, prevents file accumulation.

##### Elements
- Clear labels: “User Browser”, “Django Web Server”, “mc_and_datasheet App”, “cleanup_sessions App”, “SQLite3 DB”, “media/uploads”, “Model Card Toolkit”, “GitHub Actions”
- HTTP(S) requests/responses
- DB read/write
- Filesystem write/read
- Library invocation calls
- CI/CD flow (push → test → build → deploy)
- Orange for external libraries/services

##### Essential architectural elements
- Session management and cleanup is clearly shown (session cookie → cleanup job).
- Use of external card‐generation libraries as sub‐components of mc_and_datasheet.
- Docker container boundary, with mounted volumes for media/uploads and SQLite3.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        UserBrowser["User Browser"]:::frontend
        StaticAssets["Static Assets (CSS/JS)"]:::frontend
    end

    %% Application Layer (Docker Container)
    subgraph "Docker Container" 
        direction TB
        subgraph "Django Framework (mysite)" 
            direction TB
            DjangoURLs["URL Routing (mysite/urls.py)"]:::backend
            WSGI["WSGI Entry (mysite/wsgi.py)"]:::backend
            ASGI["ASGI Entry (mysite/asgi.py)"]:::backend
        end
        subgraph "mc_and_datasheet App" 
            direction TB
            MCD_URLs["URL Routing (mc_and_datasheet/urls.py)"]:::backend
            MCD_Views["Views (mc_and_datasheet/views.py)"]:::backend
            MCD_Forms["Forms (mc_and_datasheet/forms.py)"]:::backend
            MCD_Models["Models (mc_and_datasheet/models.py)"]:::backend
            MCD_Templates["Templates (mc_and_datasheet/templates/mc_and_datasheet/)"]:::frontend
            MCD_Static["Static (mc_and_datasheet/static/mc_and_datasheet/)"]:::frontend
        end
        subgraph "cleanup_sessions App"
            direction TB
            CS_App["App Directory (cleanup_sessions/)"]:::backend
            CS_Command["Mgmt Command (cleanup_sessions/management/commands/cleanup_sessions.py)"]:::backend
            CS_Models["Models (cleanup_sessions/models.py)"]:::backend
            CS_Views["Views (cleanup_sessions/views.py)"]:::backend
        end
        DjangoAdmin["Django Admin"]:::backend
        ManagePy["manage.py"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        SQLiteDB["SQLite3 Database"]:::storage
        MediaUploads["File Storage (media/uploads)"]:::storage
    end

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        Toolkit["Model Card Toolkit"]:::external
        FEA_LIB["featai_lib"]:::external
        DatasheetGen["Data-sheet Generator"]:::external
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        GitHubActions["GitHub Actions"]:::pipeline
        DockerfileNode["Dockerfile"]:::pipeline
        TestInput["Test Fixtures (test_input/)"]:::pipeline
    end

    %% Connections
    UserBrowser -->|"HTTP(S) Request"| DjangoURLs
    StaticAssets --> UserBrowser
    DjangoURLs --> MCD_Views
    MCD_Views --> MCD_Forms
    MCD_Views --> MCD_Models
    MCD_Views --> MediaUploads
    MCD_Views --> SQLiteDB
    MCD_Views --> Toolkit
    MCD_Views --> FEA_LIB
    MCD_Views --> DatasheetGen
    MCD_Views --> UserBrowser
    CS_Command --> MediaUploads
    CS_Command --> SQLiteDB
    CS_Command --> CS_Models
    GitHubActions -->|runs tests| DjangoURLs
    GitHubActions -->|builds image| DockerfileNode
    GitHubActions -->|uses fixtures| TestInput
    DockerfileNode --> DjangoURLs
    ManagePy --> DjangoURLs
    DjangoAdmin --> SQLiteDB

    %% Click Events
    click DjangoURLs "https://github.com/aix-group/webcards/blob/main/mysite/urls.py"
    click WSGI "https://github.com/aix-group/webcards/blob/main/mysite/wsgi.py"
    click ASGI "https://github.com/aix-group/webcards/blob/main/mysite/asgi.py"
    click MCD_URLs "https://github.com/aix-group/webcards/blob/main/mc_and_datasheet/urls.py"
    click MCD_Views "https://github.com/aix-group/webcards/blob/main/mc_and_datasheet/views.py"
    click MCD_Forms "https://github.com/aix-group/webcards/blob/main/mc_and_datasheet/forms.py"
    click MCD_Models "https://github.com/aix-group/webcards/blob/main/mc_and_datasheet/models.py"
    click MCD_Templates "https://github.com/aix-group/webcards/tree/main/mc_and_datasheet/templates/mc_and_datasheet/"
    click MCD_Static "https://github.com/aix-group/webcards/tree/main/mc_and_datasheet/static/mc_and_datasheet/"
    click CS_App "https://github.com/aix-group/webcards/tree/main/cleanup_sessions/"
    click CS_Command "https://github.com/aix-group/webcards/blob/main/cleanup_sessions/management/commands/cleanup_sessions.py"
    click CS_Models "https://github.com/aix-group/webcards/blob/main/cleanup_sessions/models.py"
    click CS_Views "https://github.com/aix-group/webcards/blob/main/cleanup_sessions/views.py"
    click Toolkit "https://github.com/aix-group/webcards/blob/main/utils/model_card_toolkit-2.0.0.dev0-py3-none-any.whl"
    click FEA_LIB "https://github.com/aix-group/webcards/blob/main/utils/model_card_lib_v2.py"
    click DatasheetGen "https://github.com/aix-group/webcards/blob/main/utils/datasheet.py"
    click SQLiteDB "https://github.com/aix-group/webcards/blob/main/db.sqlite3.zip"
    click GitHubActions "https://github.com/aix-group/webcards/blob/main/.github/workflows/django-test.yaml"
    click DockerfileNode "https://github.com/aix-group/webcards/tree/main/Dockerfile"
    click ManagePy "https://github.com/aix-group/webcards/blob/main/manage.py"
    click TestInput "https://github.com/aix-group/webcards/tree/main/test_input/"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#006064;
    classDef backend fill:#e3f2fd,stroke:#0d47a1,color:#0d47a1;
    classDef storage fill:#fff9c4,stroke:#f57f17,color:#f57f17;
    classDef external fill:#ffe0b2,stroke:#e65100,color:#e65100;
    classDef pipeline fill:#eceff1,stroke:#37474f,color:#37474f;
```
