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

241 lines
9.2 KiB
Markdown
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:
```text
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
```mermaid
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.
Reference in New Issue View Git Blame Copy Permalink