# protossgp32/retrodev-docs architecture

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

- Interactive diagram: https://gitdiagram.com/protossgp32/retrodev-docs
- Repository: https://github.com/protossgp32/retrodev-docs

## Overview

##### Project type and purpose
- This is primarily a static documentation site (built with Quarto and published via GitHub Pages)
- It includes two self-hosted server projects under “projects/…” that illustrate deployment stacks for retro development tools

##### File structure
- Top-level:
– `.github/workflows/quarto-publish.yml` → CI pipeline
– `docs/` → Quarto source files, custom extensions, images, styles
– `projects/self-hosted-servers/parts-db` → Docker Compose for parts-database
– `projects/self-hosted-servers/pso-server` → Dockerfile + executables (newserv, phosg, resource_dasm)
- README.md describes the overall goal: “easing deployment of software development environment for retro consoles”

##### README for technical stack
- Quarto (for docs)
- GitHub Actions (CI/CD)
- GitHub Pages (hosting the site)
- Docker Compose & individual Docker images (self-hosted servers)

##### Main components
a. **Developer environment** (local) – checks out repo, edits Quarto files, builds locally
b. **Version control & CI/CD**
- GitHub repo (with submodules)
- GitHub Actions workflow (quarto-publish.yml)
- Quarto build process
- Deployment to GitHub Pages
c. **Documentation site**
- Quarto source (`docs/*.qmd`, `_extensions`, `styles.css`)
- Static output (HTML + assets)
d. **Self-hosted server deployments**
1. **Parts-DB**
- Docker Compose stack:
– Database (PostgreSQL or similar)
– Web API service (e.g., a Python/Node app)
– Reverse proxy (optional)
2. **PSO-server**
- Dockerfile builds an image including:
– `newserv` (game server binary)
– `phosg` (utility library)
– `resource_dasm` (asset converter)
- Published to container registry (optional)

##### Relationships & interactions
- Developer → pushes commits → GitHub → triggers GitHub Actions
- Actions → runs Quarto build → produces static site → deploys to GitHub Pages
- End users → browse site on GitHub Pages → follow guides under `/deploy-guides`
- Guides reference the “projects” subfolder → user runs Docker Compose or `docker build && docker run`
- User ↔ self-hosted servers (HTTP/S requests to Parts-DB API or PSO server)

##### Architectural patterns & design principles
- **Static site generation** for docs (separation of content vs. runtime)
- **CI/CD pipeline** enforcing reproducible builds
- **Containerization** for server components (Docker Compose for multi-container stacks, single Dockerfile for custom servers)
- **Modularity** via Quarto extensions and Git submodules

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Environment
    Developer["Developer Environment\n(Local)"]:::dev
    Developer -->|"git push"| GitHubRepo

    %% CI/CD Pipeline
    GitHubRepo["GitHub Repo"]:::cicd
    GitHubRepo --> GitSubmodules
    GitHubRepo --> GitHubActions
    GitSubmodules["Git Submodules\n(.gitmodules)"]:::cicd
    GitHubActions["GitHub Actions Workflow"]:::cicd
    GitHubActions -->|"run Quarto build"| QuartoBuild

    %% Quarto Build and Deployment
    QuartoBuild["Quarto Build"]:::cicd
    QuartoBuild -->|"deploy static site"| GitHubPages
    GitHubPages["GitHub Pages Hosting"]:::external
    GitHubPages --> StaticSite

    %% Static Site and End User
    StaticSite["Static Site\n(HTML + Assets)"]:::docs
    StaticSite --> EndUser
    EndUser["End User Browser"]:::external
    EndUser -->|"follow guides"| PartsDBComp
    EndUser -->|"HTTP request"| PSOComp

    %% Self-Hosted Servers
    subgraph "Self-Hosted Servers"
        style Self-Hosted Servers fill:none,stroke:none
        subgraph "Parts-DB Stack"
            PartsDBComp["Docker Compose\n(parts-db)"]:::container
            PartsDBComp --> DB
            PartsDBComp --> API
            PartsDBComp --> Proxy
            DB["Database\n(PostgreSQL)"]:::container
            API["Web API Service"]:::container
            Proxy["Reverse Proxy"]:::container
        end
        subgraph "PSO Server"
            PSOComp["pso-server Directory"]:::container
            PSOComp --> DF
            PSOComp --> DI
            PSOComp --> NS
            PSOComp --> PG
            PSOComp --> RD
            DF["Dockerfile"]:::container
            DI[".dockerignore"]:::container
            NS["newserv"]:::container
            PG["phosg"]:::container
            RD["resource_dasm"]:::container
        end
    end

    %% Click events
    click Developer "https://github.com/protossgp32/retrodev-docs/tree/main//"
    click GitHubActions "https://github.com/protossgp32/retrodev-docs/blob/main/.github/workflows/quarto-publish.yml"
    click GitSubmodules "https://github.com/protossgp32/retrodev-docs/blob/main/.gitmodules"
    click StaticSite "https://github.com/protossgp32/retrodev-docs/tree/main/docs/"
    click PartsDBComp "https://github.com/protossgp32/retrodev-docs/blob/main/projects/self-hosted-servers/parts-db/docker-compose.yaml"
    click PSOComp "https://github.com/protossgp32/retrodev-docs/tree/main/projects/self-hosted-servers/pso-server/"
    click DF "https://github.com/protossgp32/retrodev-docs/tree/main/projects/self-hosted-servers/pso-server/Dockerfile"
    click DI "https://github.com/protossgp32/retrodev-docs/blob/main/projects/self-hosted-servers/pso-server/.dockerignore"
    click NS "https://github.com/protossgp32/retrodev-docs/tree/main/projects/self-hosted-servers/pso-server/newserv"
    click PG "https://github.com/protossgp32/retrodev-docs/tree/main/projects/self-hosted-servers/pso-server/phosg"
    click RD "https://github.com/protossgp32/retrodev-docs/tree/main/projects/self-hosted-servers/pso-server/resource_dasm"

    %% Styles
    classDef dev fill:#cce5ff,stroke:#004085,color:#004085;
    classDef cicd fill:#b8daff,stroke:#004085,color:#004085;
    classDef docs fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#f5c6cb,stroke:#721c24,color:#721c24;
    classDef container fill:#fff3cd,stroke:#856404,color:#856404;
```
