AI-Development-Server/docs/ARCHITECTURE.md

Atlas Architecture

This document separates confirmed current architecture from planned architecture. Do not describe planned components as installed until they have been verified.

Current Architecture

Atlas is a single physical development server.

Physical Server Overview

• Hostname: atlas
• Operating system: Ubuntu 26.04 LTS
• Hardware model: ASUS PRIME B450-PLUS
• CPU: AMD Ryzen 7 2700
• Memory: 16 GB RAM
• Architecture: x86-64
• Role: AI development server and infrastructure automation host

Storage Layout

• OS volume: SSD using LVM, mounted at /
• SQL data volume: SSD mounted at /sql
• Development volume: SSD mounted at /srv
• Repository root: /srv/repos
• Infrastructure repository: /srv/repos/AI-Development-Server

The intended model separates operating system state, SQL data, and development data. This supports rebuild and recovery by reducing reliance on the OS volume for mutable project data.

Network Identity

• Hostname: atlas
• Static IP address: 192.168.10.10
• Default gateway: 192.168.10.1
• Primary network interface: enp3s0
• Gitea SSH remote for this repository: git@git.catherinelynwood.com:atlas-bot/AI-Development-Server.git

DNS, firewall, public exposure, and TLS policy are TODO: Confirm during the relevant implementation phase.

Repository and Source-Control Flow

Git is the source of truth for repository state. Atlas holds the working copy under /srv/repos/AI-Development-Server, and Gitea is the remote source-control system for this infrastructure repository.

Expected flow:

1. Plan infrastructure changes in documentation.
2. Implement scripts, templates, or documentation updates.
3. Validate locally on Atlas.
4. Review the full diff.
5. Commit only after explicit approval.
6. Push reviewed commits to Gitea.

Branching policy is TODO: Confirm during the relevant implementation phase.

Planned Architecture

The repository is intended to grow into the version-controlled control plane for Atlas. Planned components include:

• Idempotent installation scripts under install/.
• Shared installer framework libraries under install/lib/.
• Managed configuration templates under config/ and templates/.
• Operational scripts under scripts/.
• Smoke tests under tests/.
• Rebuild and recovery procedures under docs/.
• Architecture Decision Records under docs/adr/.

Intended Development Platform Components

Atlas is intended to support:

• Codex CLI usage.
• Git and Git LFS workflows.
• Node.js-based tooling where required.
• .NET SDKs when application requirements are confirmed.
• SQL Server when the database phase is implemented.
• nginx when reverse proxy requirements are confirmed.
• Docker when runtime policy is confirmed.
• Backup, restore, monitoring, and maintenance automation.

Only components verified during implementation should be recorded as installed.

Intended PlotDirector Deployment Topology

PlotDirector deployment topology is not yet established.

Current assumptions:

• Source repositories should live under /srv/repos.
• Build artefacts should be generated outside this infrastructure repository.
• Deployed applications should be separated from source repositories.
• SQL data should use /sql once SQL Server paths are confirmed.
• nginx may act as the reverse proxy if the application is exposed over HTTP or HTTPS.
• Docker may host one or more services if containerisation is adopted.

Specific PlotDirector service names, ports, deployment paths, database names, and rollback procedures are TODO: Confirm during the relevant implementation phase.

Role of nginx

nginx is planned as the likely local reverse proxy for HTTP and HTTPS applications. Its future responsibilities may include:

• Routing requests to application services.
• TLS termination.
• Static file serving where appropriate.
• Request size, timeout, and header policy.

nginx installation, site layout, TLS certificate handling, and exposure rules are TODO: Confirm during the relevant implementation phase.

Role of SQL Server

Native SQL Server packages are not currently used because Microsoft does not publish a supported native SQL Server repository for Ubuntu 26.04. Atlas runs SQL Server 2025 Developer through Microsoft's official Linux container image instead.

• Compose project: atlas-sql
• Container: atlas-sql-server
• Image: mcr.microsoft.com/mssql/server:2025-CU1-ubuntu-24.04
• Digest: sha256:698682bab57c02c42bc0aa274b158aeb242d8e9104149a7489628d5535805816
• Edition: SQL Server 2025 Developer
• Product version: 17.0.4006.2
• Persistent storage: /sql/mssql
• Secret environment file: /etc/atlas/sql-server.env

The live SQL administrator password is not stored in Git.

Role of Docker

Docker Engine is installed from Docker's official signed Ubuntu APT repository for resolute.

• Docker Engine: 29.6.1
• Docker Compose plugin: v5.3.1
• Docker Buildx plugin: v0.35.0
• containerd.io: 2.2.5
• User nick is a member of the docker group.

A new login may be required before all shells pick up Docker group membership.

Separation of Concerns

The intended storage and responsibility model is:

• Source repositories: /srv/repos
• Infrastructure repository: /srv/repos/AI-Development-Server
• Installer logs: /var/log/atlas/install/
• Discovery and validation reports: /var/log/atlas/reports/
• Future installer state and markers: /var/lib/atlas/
• Build artefacts: TODO: Confirm during the relevant implementation phase.
• Deployed applications: TODO: Confirm during the relevant implementation phase.
• SQL data: /sql
• SQL Server container storage: /sql/mssql
• Backups: TODO: Confirm during the relevant implementation phase.
• Temporary files: system temporary locations or script-created mktemp paths
• Live secrets: outside this repository

Trust Boundaries

Known trust boundaries:

• Atlas local OS user accounts.
• SSH access to Atlas.
• SSH access from Atlas to Gitea.
• Root-level operations performed through sudo.
• Repository content versus live secret-bearing configuration.
• SQL data on /sql versus source and scripts on /srv.
• Future public-facing application traffic through nginx, if enabled.

Unresolved trust-boundary details:

• Firewall policy: TODO: Confirm during the relevant implementation phase.
• Production access model: TODO: Confirm during the relevant implementation phase.
• Secret storage model: TODO: Confirm during the relevant implementation phase.
• Backup encryption model: TODO: Confirm during the relevant implementation phase.

High-Level Diagram

flowchart TB
    Nick[Nick] -->|reviews plans and diffs| Git[Gitea Remote]
    ChatGPT[ChatGPT] -->|planning and review support| Nick
    Codex[Codex CLI on Atlas] -->|implements approved changes| Repo
    Git <--> Repo[Infrastructure repository<br>/srv/repos/AI-Development-Server]

    subgraph Atlas[atlas<br>Ubuntu 26.04 LTS<br>192.168.10.10]
        Repo
        Source[Application source repositories<br>/srv/repos]
        Install[Future install automation<br>install/]
        Config[Future config templates<br>config/ and templates/]
        Scripts[Future operational scripts<br>scripts/]
        Tests[Future smoke tests<br>tests/]
        SQL[(SQL data volume<br>/sql)]
        Deploy[Future deployed applications]
        Nginx[Future nginx reverse proxy]
        Docker[Future Docker runtime]
    end

    Repo --> Install
    Repo --> Config
    Repo --> Scripts
    Repo --> Tests
    Source --> Deploy
    Deploy --> SQL
    Nginx --> Deploy
    Docker --> Deploy

Decisions Not Yet Made

• Backup destination, schedule, retention, encryption, and restore testing.
• SQL Server version, installation method, and data layout.
• nginx site layout, TLS model, and exposure policy.
• Docker installation method and runtime policy.
• PlotDirector topology, service names, ports, paths, and rollback process.
• Monitoring stack and alerting channels.
• Branching and release policy.
• CI model.
• Firewall policy.
• Production access model.