atlas-bot/AI-Development-Server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
AI-Development-Server/docs/ARCHITECTURE.md

9.2 KiB
Raw Permalink Blame History

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
  • PlotDirector source repository: /srv/repos/PlotDirector
  • PlotDirector development deployment: /srv/apps/plotdirector-dev/current

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

UFW is active with default deny incoming and default allow outgoing. Inbound SSH 22, HTTP 80, and HTTPS 443 are allowed. SQL Server 1433 is allowed only from 192.168.10.0/24 and is bound to 192.168.10.10.

Public DNS, TLS, and router exposure 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.

PlotDirector Development Deployment Topology

PlotDirector is deployed for development from the onboarding branch.

  • Repository: git@git.catherinelynwood.com:nick/PlotDirector.git
  • Source path: /srv/repos/PlotDirector
  • Entry project: PlotLine/PlotLine.csproj
  • Target framework: net10.0
  • Output assembly: PlotLine.dll
  • Published path: /srv/apps/plotdirector-dev/current
  • Uploads path: /srv/apps/plotdirector-dev/uploads
  • Runtime environment file: /etc/plotdirector/plotdirector.env
  • Service account: plotdirector
  • systemd service: plotdirector-dev
  • Kestrel endpoint: http://127.0.0.1:5050
  • nginx hostname: dev.plotdirector.com
  • Development database: PlotDirector_Development
  • SQL login: plotdirector_dev

Windows LAN clients can test the development site with this hosts-file entry:

192.168.10.10 dev.plotdirector.com

SMTP, Stripe, and OpenAI are intentionally unconfigured in the Atlas development runtime unless explicitly provided through protected runtime configuration.

Role of nginx

nginx is installed from the standard Ubuntu 26.04 repositories and currently serves a temporary Atlas HTTP status site.

  • Package version: nginx 1.28.3
  • Service: nginx
  • Site configuration: /etc/nginx/sites-available/atlas-default.conf
  • Version-controlled source: config/nginx/atlas-default.conf
  • Static site root: /var/www/atlas
  • Health endpoint: http://192.168.10.10/health
  • PlotDirector development proxy source: config/nginx/plotdirector-dev.conf
  • PlotDirector development hostname: dev.plotdirector.com

HTTPS and TLS certificates are not configured yet.

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
  • PlotDirector source repository: /srv/repos/PlotDirector
  • PlotDirector published application: /srv/apps/plotdirector-dev/current
  • PlotDirector runtime configuration: /etc/plotdirector/plotdirector.env
  • PlotDirector uploads: /srv/apps/plotdirector-dev/uploads
  • 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.
  • PlotDirector Kestrel listens only on loopback and is reached through nginx.

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[PlotDirector dev deployment<br>/srv/apps/plotdirector-dev/current]
        Nginx[nginx reverse proxy<br>dev.plotdirector.com]
        Docker[Docker runtime]
        SqlContainer[SQL Server container<br>atlas-sql-server]
    end

    Repo --> Install
    Repo --> Config
    Repo --> Scripts
    Repo --> Tests
    Source --> Deploy
    Deploy --> SqlContainer
    SqlContainer --> 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.