# basictheprogram/crossfire-nexxus architecture

> Architecture diagram of the GitHub repository basictheprogram/crossfire-nexxus, 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/basictheprogram/crossfire-nexxus
- Repository: https://github.com/basictheprogram/crossfire-nexxus

## Overview

- A VSCode Dev Container configuration
- A Django/ASGI application (“core” + “nexxus” under src/)
- Supporting tooling (uv CLI, Ruff, pytest, pre-commit)
- CI/CD pipelines (GitHub Actions)
- Docker and Docker-Compose orchestrating local dev services (app container, database, init scripts)

##### Project type & purpose
- This is primarily a **development-environment configuration** repository (VSCode remote container + Docker Compose)
- It also contains a **Python web application** (Django/ASGI “core” project + “nexxus” app) used as demonstration or cookie-cutter template for FastAPI/Django use cases.
- Key indicators: `.devcontainer/`, `Dockerfile`, `docker-compose.yml`, VSCode settings, GitHub Actions workflows, `src/core` + `src/nexxus`.

##### File structure
- Top-level infra directories:
- `.devcontainer/` – VSCode dev container definition (Dockerfile + compose)
- `docker/` – additional compose files or Rust-build Docker
- `.github/workflows/` – CI pipelines for Docker build, Pyright, Ruff, pytest
- Main application code: `src/core` (settings, ASGI/Wsgi, URLs), `src/nexxus` (models, views, templates, static assets, migrations)
- Tooling folders: `tools/` (config, logger, tracer modules), root config files (`pyproject.toml`, `ruff.toml`, `pytest.ini`, `.pre-commit-config.yaml`)
- Documentation under `docs/` covering usage, configurations, guides, and use cases.

##### Extract architecture insights from README
- Dev container installs dev-only deps: pre-commit, pyright, pytest, ruff
- GitHub Actions mirror local environment checks (docker build, type checks, lint, tests)
- Encourages standard VSCode settings, extensions, and workflows for consistency.

##### Main components & interactions
a. **Developer workstation (host)**
- VSCode with Remote-Containers extension attaches to the dev container
b. **Dev Container (Docker Compose network)**
- **`app` service** – built from `.devcontainer/Dockerfile`, runs Python, uv CLI, lint/test tools, and hosts the Django/ASGI application (via `uvicorn` or WSGI server)
- **`db` service** – initializes database (PostgreSQL or other) via `docker-entrypoint-initdb.d/*.sql`
- Shared **volumes** for code and static/media, **network** for inter-container communication
c. **CI/CD (GitHub Actions)**
- Pipelines triggered by push/PR, running Docker builds, pyright type checks, Ruff lint/format, pytest suites
d. **Local tooling**
- `uv` CLI orchestrates dependency sync, tests, linting, formatting, cookiecutter templates
- pre-commit hooks invoked on commit for linting and formatting

##### Architectural patterns & design principles
- **Separation of concerns**: development container vs. host machine; application code vs. environment config
- **Containerization**: each service in its own container, reproducible dev environment
- **Modular code structure**: Django core + app; standalone `tools/` modules for logging/tracing/config
- **Infrastructure as code**: Dockerfiles, compose files, GitHub Actions YAML
- **DevOps integration**: local dev (VSCode + Docker) mirrors CI pipelines

##### Essential elements
- Host machine (VSCode)
- Dev Container service cluster (via Docker Compose) with labeled services
- Application code boundaries vs. environment config
- Database service and init volume
- CI/CD runner and workflow steps
- Tools (uv CLI, Ruff, pytest) as sidecar or annotations
- Network connections and volume mounts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Machine
    Host["Developer Workstation<br/>(VSCode + Remote-Containers)"]:::host
    click Host "https://github.com/basictheprogram/crossfire-nexxus/blob/main/.devcontainer/devcontainer.json"
    
    %% Dev Container Cluster
    subgraph "Dev Container (Docker Compose)"
      direction TB
      DCDef["Dev Container Definition<br/>(Dockerfile)"]:::container
      click DCDef "https://github.com/basictheprogram/crossfire-nexxus/tree/main/.devcontainer/Dockerfile"
      DCComp["Dev Container Compose<br/>(docker-compose.yml)"]:::container
      click DCComp "https://github.com/basictheprogram/crossfire-nexxus/blob/main/.devcontainer/docker-compose.yml"
      
      subgraph Services
        direction TB
        App["app: Python container<br>(uv CLI, Django/ASGI)"]:::container
        DB["db: PostgreSQL container"]:::container
        InitDB["DB Init Scripts"]:::storage
        click InitDB "https://github.com/basictheprogram/crossfire-nexxus/blob/main/.devcontainer/docker-entrypoint-initdb.d/001-user.sql"
      end
      
      Volumes["Code & Static/Media Volumes"]:::storage
      Network["Docker Compose Network"]:::network
    end
    
    %% Alternative Compose setups
    RootComp["Root docker-compose.yml"]:::container
    click RootComp "https://github.com/basictheprogram/crossfire-nexxus/blob/main/docker-compose.yml"
    AltComp["Additional Compose"]:::container
    click AltComp "https://github.com/basictheprogram/crossfire-nexxus/blob/main/docker/docker-compose.yml"
    
    %% Application Code
    subgraph "Application Code"
      direction TB
      subgraph "Core Project (src/core)"
        direction TB
        CoreSettings["settings.py"]:::appcode
        click CoreSettings "https://github.com/basictheprogram/crossfire-nexxus/blob/main/src/core/settings.py"
        CoreASGI["asgi.py"]:::appcode
        click CoreASGI "https://github.com/basictheprogram/crossfire-nexxus/blob/main/src/core/asgi.py"
        CoreWSGI["wsgi.py"]:::appcode
        click CoreWSGI "https://github.com/basictheprogram/crossfire-nexxus/blob/main/src/core/wsgi.py"
        CoreURLs["urls.py"]:::appcode
        click CoreURLs "https://github.com/basictheprogram/crossfire-nexxus/blob/main/src/core/urls.py"
      end
      subgraph "Nexxus App (src/nexxus)"
        direction TB
        NexModels["models.py"]:::appcode
        click NexModels "https://github.com/basictheprogram/crossfire-nexxus/blob/main/src/nexxus/models.py"
        NexViews["views.py"]:::appcode
        click NexViews "https://github.com/basictheprogram/crossfire-nexxus/blob/main/src/nexxus/views.py"
        NexURLs["urls.py"]:::appcode
        click NexURLs "https://github.com/basictheprogram/crossfire-nexxus/blob/main/src/nexxus/urls.py"
        NexTemplates["templates/"]:::appcode
        click NexTemplates "https://github.com/basictheprogram/crossfire-nexxus/tree/main/src/nexxus/templates/"
        NexStatic["static/"]:::appcode
        click NexStatic "https://github.com/basictheprogram/crossfire-nexxus/tree/main/src/nexxus/static/"
      end
      Manage["manage.py"]:::appcode
      click Manage "https://github.com/basictheprogram/crossfire-nexxus/blob/main/src/manage.py"
    end
    
    %% Local Tooling
    subgraph "Local Tooling Modules"
      direction TB
      UVCLI["uv CLI"]:::tool
      PreCommit["pre-commit hooks"]:::tool
      PytestTool["pytest"]:::tool
      RuffTool["Ruff"]:::tool
      subgraph "Tools Code (tools/)"
        direction TB
        ToolConfig["settings.py"]:::tool
        click ToolConfig "https://github.com/basictheprogram/crossfire-nexxus/blob/main/tools/config/settings.py"
        ToolLogger["logger.py"]:::tool
        click ToolLogger "https://github.com/basictheprogram/crossfire-nexxus/blob/main/tools/logger/logger.py"
        ToolTracer["timer.py"]:::tool
        click ToolTracer "https://github.com/basictheprogram/crossfire-nexxus/blob/main/tools/tracer/timer.py"
      end
    end
    
    %% CI/CD
    CI["CI Runner<br/>(GitHub Actions)"]:::ci
    click CI "https://github.com/basictheprogram/crossfire-nexxus/blob/main/.github/workflows/docker.yml"
    subgraph "GitHub Actions Workflows"
      direction TB
      WorkflowDocker["docker.yml"]:::workflow
      click WorkflowDocker "https://github.com/basictheprogram/crossfire-nexxus/blob/main/.github/workflows/docker.yml"
      WorkflowPyright["pyright.yml"]:::workflow
      click WorkflowPyright "https://github.com/basictheprogram/crossfire-nexxus/blob/main/.github/workflows/pyright.yml"
      WorkflowRuff["ruff.yml"]:::workflow
      click WorkflowRuff "https://github.com/basictheprogram/crossfire-nexxus/blob/main/.github/workflows/ruff.yml"
      WorkflowTest["test.yml"]:::workflow
      click WorkflowTest "https://github.com/basictheprogram/crossfire-nexxus/blob/main/.github/workflows/test.yml"
      subgraph "Custom Actions"
        direction TB
        ActionUV["setup-python-with-uv"]:::action
        click ActionUV "https://github.com/basictheprogram/crossfire-nexxus/blob/main/.github/actions/setup-python-with-uv/action.yml"
        ActionGit["setup-git-config"]:::action
        click ActionGit "https://github.com/basictheprogram/crossfire-nexxus/blob/main/.github/actions/setup-git-config/action.yml"
      end
    end
    
    %% Documentation and Config
    Docs["Documentation (docs/)"]:::appcode
    click Docs "https://github.com/basictheprogram/crossfire-nexxus/blob/main/docs/getting-started/devcontainer.md"
    click Docs "https://github.com/basictheprogram/crossfire-nexxus/blob/main/docs/configurations/uv.md"
    click Docs "https://github.com/basictheprogram/crossfire-nexxus/blob/main/docs/guides/tools/logger.md"
    VCSettings["VSCode Settings"]:::host
    click VCSettings "https://github.com/basictheprogram/crossfire-nexxus/tree/main/.vscode/"
    PyProject["pyproject.toml"]:::appcode
    click PyProject "https://github.com/basictheprogram/crossfire-nexxus/blob/main/pyproject.toml"
    PytestINI["pytest.ini"]:::appcode
    click PytestINI "https://github.com/basictheprogram/crossfire-nexxus/blob/main/pytest.ini"
    RuffConfig["ruff.toml"]:::appcode
    click RuffConfig "https://github.com/basictheprogram/crossfire-nexxus/blob/main/ruff.toml"
    PyrightCFG["pyrightconfig.json"]:::appcode
    click PyrightCFG "https://github.com/basictheprogram/crossfire-nexxus/blob/main/pyrightconfig.json"
    PreCommitCfg[".pre-commit-config.yaml"]:::appcode
    click PreCommitCfg "https://github.com/basictheprogram/crossfire-nexxus/blob/main/.pre-commit-config.yaml"
    
    %% Connections
    Host -->|"Remote-Containers"| DCDef
    Host --> DCComp
    DCComp --> App
    DCComp --> DB
    DCComp --> Volumes
    DCComp --> Network
    DB -->|uses| InitDB
    App -->|mounts code| CoreSettings
    App -->|executes| Manage
    App -->|imports| UVCLI
    App -->|runs| PreCommit
    App -->|runs| PytestTool
    App -->|runs| RuffTool
    App -->|connects via SQL| DB
    CI --> WorkflowDocker
    CI --> WorkflowPyright
    CI --> WorkflowRuff
    CI --> WorkflowTest
    WorkflowDocker -->|builds| DCDef
    WorkflowPyright -->|type-checks| CoreSettings
    WorkflowRuff -->|lints| CoreSettings
    WorkflowTest -->|tests| PytestTool
    
    %% Styles
    classDef host fill:#f9f,stroke:#333,stroke-width:1px
    classDef container fill:#bbf,stroke:#333,stroke-width:1px
    classDef storage fill:#bfb,stroke:#333
    classDef network fill:#ffd,stroke:#333
    classDef ci fill:#fdd,stroke:#333
    classDef workflow fill:#fee,stroke:#a66
    classDef action fill:#fdf,stroke:#a66
    classDef appcode fill:#dfd,stroke:#333
    classDef tool fill:#ffd,stroke:#333
```
