# dimitrijd/iron architecture

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

## Overview

##### Project type and purpose
- This is not a typical app but a Docker‐based developer environment image (“ferrum”) that bundles:
- dumb-init + supervisord for process supervision
- code-server (VS Code in the browser)
- Node.js (via nvm), MongoDB, zsh
- Helper scripts and configs for building/running in “base”, “stack” and “dev” modes
- The README shows run instructions, port mappings and a set of TODOs for build options and helper features.

##### File structure
- Top-level:
- Dockerfile, .dockerignore, .gitignore, README.md
- code-server/ (service files & config for code-server)
- mongo/ (mongod config & supervisord conf)
- scripts/ (build/run helper scripts: base.sh, stack.sh, dev.sh)
- help/ (shell helpers for user guidance on the host)
- supervisord/ (global supervisord.conf)
- Patterns: layered builds (scripts/base.sh, scripts/stack.sh, scripts/dev.sh) indicate multi-stage Docker build contexts:
- base: core OS + dumb-init, supervisor
- stack: Node + Mongo
- dev: code-server, zsh, nvm
- Supervisord orchestrates internal services; Dockerfile shells out to scripts/.

##### README for additional insights
- The run command maps ports (3000, 5000, 5500, 27017, 8443) and mounts the host project into “/coder/project”.
- TODOs list future extensions (alternative overlays, stack options, dev tools).

a. Main components
- Host machine / Docker CLI
- Docker container “ferrum”
– Init process: dumb-init
– Process supervisor: supervisord
– Service #1: MongoDB
– Service #2: code-server (with VS Code extensions)
– Shell environment: zsh + nvm + Node.js
– Helper scripts inside container (stack.sh, dev.sh)
- Host-side helper scripts (help/*) to manage the container lifecycle
- Volume mount: host “$(pwd)” → “/coder/project” inside container
b. Relationships & interactions
- Host invokes “docker run” → container
- Inside container: dumb-init → starts supervisord → launches MongoDB and code-server in parallel
- VS Code frontend (browser at port 8443) talks to local language servers in container
- Node apps (port 3000–5500) served from container, backed by MongoDB (port 27017)
- scripts/*.sh are executed at build time or run time to configure each layer
c. Architectural patterns & principles
- Layered container build (multi-stage) for separation of concerns (base, stack, dev)
- Single container supervising multiple processes (instead of one-service-per-container) using dumb-init + supervisord
- Volume-based development workflow (live code edit)
d. Key technologies/frameworks
- Docker, multi-stage builds, supervisord, dumb-init
- code-server (VS Code in browser), Node.js (nvm), MongoDB, zsh

##### Elements
- Host → Docker Build Stages → Docker Image → Runtime Container
- supervisord → MongoDB & code-server
- Browser (port 8443) → code-server
- Browser/Terminal (ports 3000–5500) → Node processes → MongoDB (port 27017)
- Volume mount: Host filesystem → /coder/project
- Rectangles for compute units (container, processes)

Final advice:
- Be exhaustive in listing each build script and config directory as its own logical component; capture “as many components as possible.”
- Use callouts or side notes to reference script names (e.g., scripts/stack.sh) and conf files (mongo/mongod.conf, code-server/config.yaml).
- Keep labels succinct but precise; anyone reading should immediately see how the Docker image is constructed, what runs at startup, and how host interactions flow into the container.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host
    Host["Host Machine"]:::host
    Host -->|"docker build"| BaseStage

    %% Build Stages
    subgraph "Build Stage: Base"
        BaseStage["Base Stage"]:::baseStage
        BS_Script["scripts/base.sh"]:::script
        BS_Dockerfile["Dockerfile (base stage)"]:::file
    end
    BaseStage --> StackStage
    click BS_Script "https://github.com/dimitrijd/iron/blob/master/scripts/base.sh"

    subgraph "Build Stage: Stack"
        StackStage["Stack Stage"]:::stackStage
        SS_Script["scripts/stack.sh"]:::script
        SS_MongoConf["mongo/mongod.conf"]:::file
        SS_MongoSup["mongo/mongod.supervisord.conf"]:::file
    end
    click SS_Script "https://github.com/dimitrijd/iron/blob/master/scripts/stack.sh"
    click SS_MongoConf "https://github.com/dimitrijd/iron/blob/master/mongo/mongod.conf"
    click SS_MongoSup "https://github.com/dimitrijd/iron/blob/master/mongo/mongod.supervisord.conf"

    StackStage --> DevStage

    subgraph "Build Stage: Dev"
        DevStage["Dev Stage"]:::devStage
        DS_Script["scripts/dev.sh"]:::script
        CS_Config["code-server/config.yaml"]:::file
        CS_ExtLatest["code-server/extensions-latest.sh"]:::file
        CS_ExtPinned["code-server/extensions-pinned.sh"]:::file
    end
    click DS_Script "https://github.com/dimitrijd/iron/blob/master/scripts/dev.sh"
    click CS_Config "https://github.com/dimitrijd/iron/blob/master/code-server/config.yaml"
    click CS_ExtLatest "https://github.com/dimitrijd/iron/blob/master/code-server/extensions-latest.sh"
    click CS_ExtPinned "https://github.com/dimitrijd/iron/blob/master/code-server/extensions-pinned.sh"

    DevStage --> DockerImage

    %% Docker Image and Runtime Container
    DockerImage["Docker Image: ferrum"]:::image
    DockerImage --> Runtime

    subgraph "Runtime Container" 
        direction TB
        Init["dumb-init (ENTRYPOINT)"]:::service
        Sup["supervisord"]:::service
        Init --> Sup

        subgraph Services
            Mongo["MongoDB"]:::database
            CodeSrv["code-server"]:::service
            ShellEnv["zsh + nvm + Node.js"]:::service
        end
        Sup --> Mongo
        Sup --> CodeSrv
        CodeSrv -->|"8443"| Browser["Browser"]:::external
        ShellEnv -->|"3000-5500"| NodeApp["Node.js Apps"]:::service
        NodeApp -->|"27017"| Mongo
    end
    click Init "https://github.com/dimitrijd/iron/tree/master/Dockerfile"
    click Sup "https://github.com/dimitrijd/iron/blob/master/supervisord/supervisord.conf"
    click CodeSrv "https://github.com/dimitrijd/iron/blob/master/code-server/code.supervisord.conf"
    click Mongo "https://github.com/dimitrijd/iron/blob/master/mongo/mongod.supervisord.conf"

    %% Volume Mount
    Host -->|"mount $(pwd) → /coder/project"| Volume["/coder/project"]:::volume
    Volume --> ShellEnv

    %% Host-side Helpers
    subgraph "Host-Side Helper Utilities" 
        style HostHelpers stroke-dasharray: 5 5
        HB1["help/banner.sh"]:::script
        HB2["help/fe.sh"]:::script
        HB3["help/help.sh"]:::script
    end
    click HB1 "https://github.com/dimitrijd/iron/blob/master/help/banner.sh"
    click HB2 "https://github.com/dimitrijd/iron/blob/master/help/fe.sh"
    click HB3 "https://github.com/dimitrijd/iron/blob/master/help/help.sh"

    %% Project Root
    subgraph "Project Root"
        DR1["Dockerfile"]:::file
        DR2[".dockerignore"]:::file
        DR3[".gitignore"]:::file
        DR4["README.md"]:::file
    end
    click DR1 "https://github.com/dimitrijd/iron/tree/master/Dockerfile"

    %% Classes
    classDef host fill:#ffd2d2,stroke:#900;
    classDef baseStage fill:#e0e0ff,stroke:#333;
    classDef stackStage fill:#d0ffd0,stroke:#333;
    classDef devStage fill:#ffd0d0,stroke:#333;
    classDef image fill:#f0f0f0,stroke:#666,stroke-width:2px;
    classDef service fill:#d1ecf1,stroke:#0c5460;
    classDef database fill:#f8d7da,stroke:#721c24;
    classDef external fill:#fff3cd,stroke:#856404;
    classDef volume fill:#d4edda,stroke:#155724,stroke-dasharray: 2 2;
    classDef script fill:#fff,stroke:#666,stroke-dasharray: 5 5;
    classDef file fill:#f5f5f5,stroke:#999;
```
