# creativecommons/cc-legal-tools-app architecture

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

- Interactive diagram: https://gitdiagram.com/creativecommons/cc-legal-tools-app
- Repository: https://github.com/creativecommons/cc-legal-tools-app

## Overview

##### Main Components
- Docker Setup / Orchestration:
- Docker Compose file (docker-compose.yml) orchestrates at least two containers:
○ “app” container: Runs the Django application (which processes requests, manages the Models in legal_tools and renders templates).
○ “static” container: Serves the generated static HTML and RDF/XML pages (output from the publishing process).
- Django Application:
- Core backend code exists in the “cc_legal_tools” and “legal_tools” directories. This includes:
○ Settings are stored in cc_legal_tools/settings (with different environments such as dev, local).
○ The main Django app aspects including URL routing (urls.py), WSGI configuration (wsgi.py) and model definitions (models.py in legal_tools).
- Management commands and scripts (found in “legal_tools/management” and “i18n/management”) that handle data loading, publishing, and translation tasks.
- Data Repository and Integration:
- The README instructs that this repository be used together with the cc-legal-tools-data repo.
- The publishing command (./manage.py publish -v2) outputs static files into the “docs/” directory inside the cc-legal-tools-data repository.
- Database and Models:
- The primary models (LegalCode and Tool) represent the legal tool metadata.
- Internationalization and Static Content:
- Files under “i18n” (e.g., translation scripts, templates, and commands) facilitate multi-language support.
- Template files in the “templates” directory and static resources (CSS, JS, images, RDF files) in cc_legal_tools/static provide front-end presentation and legal text/metadata.

##### Relationships and Data Flow
- Requests enter the system via the “app” container. The Django application processes these requests by:
- Reading settings from the configuration files.
- Accessing the database via Django’s ORM and retrieving legal tool data (using models in legal_tools).
- Rendering HTML responses with templates (found in the templates/ directory) and including internationalized legal texts.
- The publishing process (initiated via a management command) generates static versions of the legal tools (HTML pages and RDF/XML metadata) and writes them into the “docs/” directory in the companion data repository.
- The “static” container serves these pre-generated files to end-users as static content (usually used on the live website).

##### Architectural Patterns and Design Principles
- Separation of concerns is clearly applied by splitting dynamic application logic (Django backend) from static content serving.
- Modular design:
- The “legal_tools” module holds all core business logic, models, and views related to legal texts.
- The “cc_legal_tools” module handles project-wide settings and static file management.
- The “i18n” module is responsible for translation functionalities.
- Containerization via Docker ensures consistent deployment and environment parity.

##### Relevant Technologies
- Python 3.11, Django 4.2 (as specified by the Pipfile, Dockerfile, and workflows).
- Docker and Docker Compose for container orchestration.
- Git for version control and integration with GitHub.
- Pre-commit hooks, flake8, Black, isort, and other development tooling for code quality.
- Transifex for managing translations (linked via the i18n functionality).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Orchestration"
        DC1["docker-compose.yml"]:::file
        DC2["Dockerfile"]:::file
    end

    subgraph "Containers"
        subgraph "App Container (Django)"
            A1["manage.py"]:::file
            A2["cc_legal_tools"]:::service
            A3["legal_tools"]:::service
            A4["Settings Module"]:::service
            A5["Internationalization (i18n)"]:::service
            A6["Static Assets"]:::service
            A7["Templates"]:::service
            A8["Publish Command"]:::file
        end
        subgraph "Static Container"
            SC1["Static File Server"]:::service
        end
    end

    subgraph "Data and Database"
        DB["Database (LegalCode, Tool)"]:::db
        ED["External Data Repository (cc-legal-tools-data)"]:::external
    end

    subgraph "Developer Tools & Documentation"
        DT1["dev"]:::file
        DT2["docs"]:::file
    end

    %% Orchestration directs containers
    DC1 -->|"orchestrates"| A1
    DC1 -->|"orchestrates"| SC1
    DC2 --> A1

    %% Django Application in App Container
    A1 --> A2
    A1 --> A3
    A2 --> A4
    A4 --> A5
    A4 --> A6
    A4 --> A7
    A3 --> A8
    A3 --> DB

    %% Publishing Process
    A8 -->|"outputs_static_files"| ED
    ED --> SC1

    %% Developer Tools relation to Documentation
    DT2 --- ED

    %% Click Events
    click DC1 "https://github.com/creativecommons/cc-legal-tools-app/blob/main/docker-compose.yml"
    click DC2 "https://github.com/creativecommons/cc-legal-tools-app/tree/main/Dockerfile"
    click A1 "https://github.com/creativecommons/cc-legal-tools-app/blob/main/manage.py"
    click A2 "https://github.com/creativecommons/cc-legal-tools-app/tree/main/cc_legal_tools/"
    click A3 "https://github.com/creativecommons/cc-legal-tools-app/tree/main/legal_tools/"
    click A4 "https://github.com/creativecommons/cc-legal-tools-app/tree/main/cc_legal_tools/settings/"
    click A5 "https://github.com/creativecommons/cc-legal-tools-app/tree/main/i18n/"
    click A6 "https://github.com/creativecommons/cc-legal-tools-app/tree/main/cc_legal_tools/static/"
    click A7 "https://github.com/creativecommons/cc-legal-tools-app/tree/main/templates/"
    click A8 "https://github.com/creativecommons/cc-legal-tools-app/blob/main/legal_tools/management/commands/publish.py"
    click DT1 "https://github.com/creativecommons/cc-legal-tools-app/tree/main/dev/"
    click DT2 "https://github.com/creativecommons/cc-legal-tools-app/tree/main/docs/"

    %% Styles
    classDef file fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef service fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef db fill:#cce5ff,stroke:#003366,stroke-width:2px,stroke-dasharray: 5, 5;
    classDef external fill:#ffffcc,stroke:#999900,stroke-width:2px;
```
