# mohanishkhatri/staging-server architecture

> Architecture diagram of the GitHub repository mohanishkhatri/staging-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohanishkhatri/staging-server
- Repository: https://github.com/mohanishkhatri/staging-server

## Overview

##### Project type and purpose
- This is a full-stack Django application (“Staging-Server”) whose job is to let developers spin up, configure, and test Docker containers on a staging subdomain. It provides a web GUI (HTML/CSS/JS), a REST/WSGI backend, asynchronous deployment via Celery, and configures Nginx dynamically.

##### File structure
- Top-level deploy files: Dockerfile, docker-compose.yml, deploy/*.sh, nginx/configs/*.conf
- Django project root:
- manage.py, stagingserver/ (settings, wsgi, asgi, celery, routing, middleware)
- apps: main/, repositories/, gitlab_social/ (models, views, services)
- static assets: assets/admin (Django admin CSS/JS), frontail (log viewer), xterm (web terminal)
- templates/ (HTML for UI)
- docs/ (setup & folder structure)
- Key patterns:
- Standard Django MVC (apps with models→views→templates)
- Celery for asynchronous tasks (stagingserver/celery.py)
- Django Channels/WebSockets for live logs and terminal (stagingserver/routing.py)
- Shell scripts for Nginx config management & container cleanup

##### Extract insights from the README
- Launch GUI to deploy any GIT repo as a Docker container
- Auto-generate Nginx vhost for each deployment
- Real-time logs (searchable) using frontail
- Interactive shell via xterm.js over WebSockets
- Asynchronous workflow (Celery)
- Environment variables, mounts, pre/post hooks

##### Main components & how they interact
a. Browser (User Interface)
- HTML templates + JS libraries (xterm.js, frontail)
- Communicates via HTTP(S) and WebSocket to the backend
b. Nginx
- Reverse proxy for the Django app and Channels (WS)
- Serves static files (admin CSS/JS, xterm.css, frontail CSS)
- Dynamically reloaded when new site vhosts are added/removed
c. Gunicorn (WSGI) / Daphne (ASGI)
- Hosts the Django application (stagingserver)
- ASGI server for Channels to support WebSockets
d. Django application
- URL routing (stagingserver/urls.py + app urls.py)
- Business logic in services.py for each app
- Models persisted in a relational database (SQLite in dev; env configurable)
e. Celery Worker + Message Broker
- Handles long-running container builds and deployments asynchronously
- Publishes task status back to Django for UI updates
f. Docker Engine
- Programmatically controlled by Django services to pull images, run containers, map ports, set env vars, mounts
g. Database
- Stores metadata: repositories, running instances, logs pointers, user data
h. External Git Repository
- Source of code to be deployed
i. Scripts & Automation
- Shell scripts under deploy/ and scripts/ for Nginx management and cleanup

##### Architectural patterns & design principles
- MVC (Django apps) with clear separation of models, views, templates
- Asynchronous task queue for non-blocking operations (Celery)
- Event-driven WS connections for real-time logs and shell (Django Channels)
- Infrastructure as code: Docker, docker-compose, Nginx configs as templates/scripts
- Modular services layer (services.py in each app) for single-responsibility

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: User Interface
    subgraph "Layer 1: Browser"
        direction TB
        Frontend_Assets["Static Assets<br/>(xterm.js, frontail)"]:::frontend
        Templates["Templates<br/>(Django HTML)"]:::frontend
    end

    %% Layer 2: Reverse Proxy
    Nginx["Nginx<br/>(Reverse Proxy & Static Server)"]:::infra

    %% Layer 3: Application Servers
    subgraph "Layer 3: App Servers"
        direction TB
        Gunicorn["Gunicorn (WSGI)"]:::backend
        Daphne["Daphne (ASGI)"]:::backend
    end

    %% Layer 4: Django Backend
    subgraph "Layer 4: Django Application"
        direction TB
        Manage["manage.py"]:::backend
        Django_Core["stagingserver<br/>(asgi.py, wsgi.py, celery.py, routing.py)"]:::backend
        subgraph "Django Apps"
            direction TB
            MainApp["main app<br/>(models, views, services)"]:::backend
            RepoApp["repositories app<br/>(models, views, services)"]:::backend
            GitLabApp["gitlab_social app<br/>(models, views, services)"]:::backend
        end
    end

    %% Layer 5: Async & Data Stores
    subgraph "Layer 5: Asynchronous & Data"
        direction TB
        Broker["Message Broker<br/>(Redis/RabbitMQ)"]:::data
        CeleryWorker["Celery Worker"]:::backend
        Database["Database<br/>(SQLite/Postgres)"]:::data
    end

    %% Layer 6: Supporting Services & External
    subgraph "Layer 6: Infrastructure & External"
        direction TB
        DockerEngine["Docker Engine"]:::external
        ExternalGit["External Git Repository"]:::external
        Scripts["Infrastructure Scripts<br/>(deploy/, scripts/)"]:::infra
    end

    %% Connections
    Frontend_Assets -->|"served by"| Nginx
    Templates -->|"served by"| Nginx
    Frontend_Assets -->|WS| Daphne
    Nginx -->|HTTP/HTTPS| Gunicorn
    Nginx -->|WS| Daphne
    Gunicorn -->|Django HTTP| Django_Core
    Daphne -->|Channels WS| Django_Core
    Django_Core -->|invokes| MainApp
    Django_Core -->|invokes| RepoApp
    Django_Core -->|invokes| GitLabApp
    Django_Core -->|reads/writes| Database
    Django_Core -->|enqueue AMQP| Broker
    Broker -->|jobs| CeleryWorker
    CeleryWorker -->|Docker API| DockerEngine
    CeleryWorker -->|update status| Database
    Django_Core -->|clone code| ExternalGit
    Django_Core -->|runs scripts| Scripts
    DockerEngine -->|logs| Frontend_Assets
    DockerEngine -->|interactive shell| Frontend_Assets

    %% Click Events
    click Frontend_Assets "https://github.com/mohanishkhatri/staging-server/tree/main/assets/frontail/"
    click Frontend_Assets "https://github.com/mohanishkhatri/staging-server/tree/main/assets/xterm/"
    click Templates "https://github.com/mohanishkhatri/staging-server/tree/main/templates/"
    click Nginx "https://github.com/mohanishkhatri/staging-server/blob/main/nginx/nginx.conf"
    click Nginx "https://github.com/mohanishkhatri/staging-server/blob/main/nginx/configs/staging.conf"
    click Nginx "https://github.com/mohanishkhatri/staging-server/blob/main/deploy/nginx_watcher.sh"
    click Nginx "https://github.com/mohanishkhatri/staging-server/blob/main/deploy/nginx_watcher.service"
    click Nginx "https://github.com/mohanishkhatri/staging-server/blob/main/deploy/template.conf"
    click Gunicorn "https://github.com/mohanishkhatri/staging-server/blob/main/deploy/gunicorn.sh"
    click Gunicorn "https://github.com/mohanishkhatri/staging-server/blob/main/docker-compose.yml"
    click Daphne "https://github.com/mohanishkhatri/staging-server/blob/main/docker-compose-v4.yml"
    click Manage "https://github.com/mohanishkhatri/staging-server/blob/main/manage.py"
    click Django_Core "https://github.com/mohanishkhatri/staging-server/blob/main/stagingserver/asgi.py"
    click Django_Core "https://github.com/mohanishkhatri/staging-server/blob/main/stagingserver/wsgi.py"
    click Django_Core "https://github.com/mohanishkhatri/staging-server/blob/main/stagingserver/celery.py"
    click MainApp "https://github.com/mohanishkhatri/staging-server/blob/main/main/services.py"
    click RepoApp "https://github.com/mohanishkhatri/staging-server/blob/main/repositories/services.py"
    click GitLabApp "https://github.com/mohanishkhatri/staging-server/blob/main/gitlab_social/services.py"
    click CeleryWorker "https://github.com/mohanishkhatri/staging-server/blob/main/stagingserver/celery.py"
    click Database "https://github.com/mohanishkhatri/staging-server/blob/main/db.sqlite3"
    click Scripts "https://github.com/mohanishkhatri/staging-server/tree/main/deploy/"
    click Scripts "https://github.com/mohanishkhatri/staging-server/blob/main/scripts/iris_container_cleanup.sh"

    %% Styles
    classDef frontend fill:#a3d5d3,stroke:#333,stroke-width:1px
    classDef backend fill:#9ec1cf,stroke:#333,stroke-width:1px
    classDef data fill:#fddbc7,stroke:#333,stroke-width:1px
    classDef infra fill:#f4a261,stroke:#333,stroke-width:1px
    classDef external fill:#e76f51,stroke:#333,stroke-width:1px
```
