docs: comprehensive README with Mermaid architecture diagram
- Full service map (18 public services documented) - Mermaid architecture diagram: Internet → Caddy → Authentik → Apps → AI - AI stack diagram: local router tiers + cloud fallback chain - Deployment guide: VPS spec, Caddy SSO pattern, env layout - Security model: perimeter, auth gates, AI kill-switch, secrets policy - Repo structure tree - Atlas branding header + shields.io badges
This commit is contained in:
Chaib Aarab
parent
6a0d6f5a8d
commit
a90a428189
3 changed files with 320 additions and 14 deletions
230
README.md
230
README.md
|
|
@ -1,23 +1,225 @@
|
||||||
# Atlas OS
|
<div align="center">
|
||||||
|
|
||||||
Browser-native desktop environment for Atlas Corporation — a full PWA served behind Authentik SSO.
|
```
|
||||||
|
█████╗ ████████╗██╗ █████╗ ███████╗
|
||||||
|
██╔══██╗╚══██╔══╝██║ ██╔══██╗██╔════╝
|
||||||
|
███████║ ██║ ██║ ███████║███████╗
|
||||||
|
██╔══██║ ██║ ██║ ██╔══██║╚════██║
|
||||||
|
██║ ██║ ██║ ███████╗██║ ██║███████║
|
||||||
|
╚═╝ ╚═╝ ╚═╝ ╚══════╝╚═╝ ╚═╝╚══════╝
|
||||||
|
O S · A I C o m m a n d C e n t e r
|
||||||
|
```
|
||||||
|
|
||||||
|
**A browser-native AI desktop — log in with your identity, get your data, run your tools.**
|
||||||
|
No install. Any device. One URL.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What it is
|
||||||
|
|
||||||
|
Atlas OS is a Citrix-style browser desktop for solo founders and small teams.
|
||||||
|
Log in once with Authentik SSO → a desktop boots with live data from your actual systems:
|
||||||
|
bank transactions, CRM leads, email drafts, fleet status, and a kill-switch for your AI agents.
|
||||||
|
|
||||||
|
**Live:** `https://command.atlascorporation.nl/os/` *(SSO required)*
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Screens
|
## Screens
|
||||||
|
|
||||||
| Screen | Data |
|
| # | Screen | Live data |
|
||||||
|--------|------|
|
|---|--------|-----------|
|
||||||
| Today | Daily brief, AI state |
|
| 1 | **Today** | AI daily brief, accountability level |
|
||||||
| Money | Bank transactions |
|
| 2 | **Money** | Bank transactions (Enable Banking) |
|
||||||
| Inbox | Email + WhatsApp drafts |
|
| 3 | **Inbox** | Email + WhatsApp drafts, flagged items |
|
||||||
| Pipeline | CRM leads |
|
| 4 | **Pipeline** | CRM leads and deal status (Odoo) |
|
||||||
| Fleet | POS terminals |
|
| 5 | **Fleet** | POS terminals, health, last-seen |
|
||||||
| Control | Kill-switch, spend cap |
|
| 6 | **Control** | AI kill-switch, daily spend cap |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TB
|
||||||
|
subgraph Internet["Internet"]
|
||||||
|
User([User / Device])
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Edge["Edge — Caddy reverse proxy"]
|
||||||
|
Caddy[Caddy TLS + rate limit]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Identity["Identity — Authentik"]
|
||||||
|
Auth[Authentik SSO forward_auth]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph OS["Atlas OS"]
|
||||||
|
Desktop[Atlas OS PWA]
|
||||||
|
Cockpit[The Mind cockpit]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Comms["Communications"]
|
||||||
|
Evolution[Evolution API WhatsApp]
|
||||||
|
Stalwart[Stalwart Mail SMTP/IMAP]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Apps["Apps"]
|
||||||
|
Odoo[Odoo 19 CE CRM+ERP]
|
||||||
|
Nextcloud[Nextcloud 31 files+cal]
|
||||||
|
Firefly[Firefly III finance]
|
||||||
|
Paperless[Paperless-ngx docs]
|
||||||
|
N8N[n8n automation]
|
||||||
|
Forgejo[Forgejo git]
|
||||||
|
Vault[Vaultwarden passwords]
|
||||||
|
MeshCentral[MeshCentral remote]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph AI["AI Layer"]
|
||||||
|
Router[Atlas LLM Router local+cloud]
|
||||||
|
Brain[Atlas Brain autonomous agent]
|
||||||
|
end
|
||||||
|
|
||||||
|
User --> Caddy
|
||||||
|
Caddy --> Auth
|
||||||
|
Auth --> Desktop
|
||||||
|
Auth --> Apps
|
||||||
|
Desktop --> Cockpit
|
||||||
|
Cockpit --> Odoo
|
||||||
|
Brain --> Router
|
||||||
|
Evolution --> Brain
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Service map
|
||||||
|
|
||||||
|
| Category | Service | URL |
|
||||||
|
|----------|---------|-----|
|
||||||
|
| Identity | Authentik SSO | auth.atlascorporation.nl |
|
||||||
|
| Identity | Vaultwarden | vault.atlascorporation.nl |
|
||||||
|
| OS | Atlas OS PWA | command.atlascorporation.nl/os/ |
|
||||||
|
| OS | Command dashboard | command.atlascorporation.nl |
|
||||||
|
| AI | Open WebUI / chat | chat.atlascorporation.nl |
|
||||||
|
| AI | Atlas Brain | internal |
|
||||||
|
| Mail | Stalwart | mail.atlascorporation.nl |
|
||||||
|
| CRM / ERP | Odoo 19 CE | odoo.atlascorporation.nl |
|
||||||
|
| Files | Nextcloud 31 | cloud.atlascorporation.nl |
|
||||||
|
| Finance | Firefly III | money.atlascorporation.nl |
|
||||||
|
| Documents | Paperless-ngx | docs.atlascorporation.nl |
|
||||||
|
| Automation | n8n | n8n.atlascorporation.nl |
|
||||||
|
| Git | Forgejo | git.atlascorporation.nl |
|
||||||
|
| Remote access | MeshCentral | mesh.atlascorporation.nl |
|
||||||
|
| Monitoring | Uptime Kuma | uptime.atlascorporation.nl |
|
||||||
|
| WhatsApp | Evolution API | internal |
|
||||||
|
| Academy | Atlas Academy | atlasacademy.nl |
|
||||||
|
| POS | AtlasPOS | atlaspos.nl |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Repo structure
|
||||||
|
|
||||||
|
```
|
||||||
|
atlas-os/
|
||||||
|
├── web/
|
||||||
|
│ ├── os.html # Atlas OS desktop PWA (6 screens, 28KB)
|
||||||
|
│ └── sitemap.html # Live service map (all 24+ services)
|
||||||
|
├── scripts/
|
||||||
|
│ ├── enis_monitor.py # WhatsApp monitor + LLM auto-reply
|
||||||
|
│ ├── enis_monitor.service # systemd unit template
|
||||||
|
│ └── *.py # Automation: finance, leads, reminders
|
||||||
|
├── patterns/
|
||||||
|
│ ├── ANTI_IMPULSE_RULES.md # Build discipline
|
||||||
|
│ └── CLUSTER_THEN_POLISH.md # UX pattern
|
||||||
|
├── docs/
|
||||||
|
│ ├── deployment.md # Full stack deployment guide
|
||||||
|
│ └── security.md # Security model
|
||||||
|
└── .gitignore # Blocks secrets, env files, credentials
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Deployment
|
## Deployment
|
||||||
|
|
||||||
Served at `https://command.atlascorporation.nl/os/` behind Authentik forward_auth.
|
### Prerequisites
|
||||||
Cockpit APIs proxied server-side — no credentials in the browser.
|
- VPS (4 vCPU / 8 GB RAM minimum — Hetzner CPX32 recommended)
|
||||||
|
- Docker + Docker Compose
|
||||||
|
- Caddy (TLS + reverse proxy)
|
||||||
|
- Domain you control
|
||||||
|
|
||||||
## Tech stack
|
### Atlas OS (Caddyfile snippet)
|
||||||
|
|
||||||
Vanilla JS PWA · Authentik SSO · Evolution API (WhatsApp) · Caddy · Docker · Hetzner
|
```caddy
|
||||||
|
command.yourdomain.com {
|
||||||
|
forward_auth authentik-server:9000 {
|
||||||
|
uri /outpost.goauthentik.io/auth/caddy
|
||||||
|
copy_headers X-Authentik-Username X-Authentik-Name X-Authentik-Email
|
||||||
|
}
|
||||||
|
handle_path /os/* {
|
||||||
|
root * /opt/atlas/atlas-desktop
|
||||||
|
file_server
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### WhatsApp monitor
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp scripts/enis_monitor.py /opt/atlas/brain/
|
||||||
|
cp scripts/enis_monitor.service /etc/systemd/system/atlas-enis-monitor.service
|
||||||
|
systemctl enable --now atlas-enis-monitor
|
||||||
|
```
|
||||||
|
|
||||||
|
The monitor only replies when the contact starts a message with `/atlas` — silent otherwise.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## AI stack
|
||||||
|
|
||||||
|
```
|
||||||
|
User message
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
Atlas Brain (Python autonomous agent)
|
||||||
|
│
|
||||||
|
├── Local router (localhost:8888)
|
||||||
|
│ ├── atlas-fast LLaMA 1B labels, routing
|
||||||
|
│ ├── atlas-free hermes3 Dutch copy, summaries
|
||||||
|
│ ├── atlas-code Qwen Coder code completion
|
||||||
|
│ └── atlas-phi3 Qwen 7B reasoning
|
||||||
|
│
|
||||||
|
└── Cloud fallback (free tier first)
|
||||||
|
├── Groq llama-3.3-70b-versatile
|
||||||
|
├── Cerebras llama-3.1-70b
|
||||||
|
└── Claude sonnet-4-6 (paid, last resort)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security model
|
||||||
|
|
||||||
|
- **All public services behind Authentik** — unauthenticated = 302 to SSO login.
|
||||||
|
- **Sensitive APIs on Tailscale only** — cockpit, Odoo internal APIs never public.
|
||||||
|
- **No secrets in git** — `.gitignore` blocks `*.env`, `*.key`, `*.sqlite`, `secrets/`, `.auth`.
|
||||||
|
- **LLM guardrails** — WhatsApp brain hard-blocks passwords, personal finance, client data.
|
||||||
|
- **Human gate for critical actions** — money movement, external comms, self-modification all require approval via the Control screen.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Built by
|
||||||
|
|
||||||
|
**Chaib Aarab** — [Atlas Corporation](https://atlascorporation.nl), Tilburg NL
|
||||||
|
|
||||||
|
Solo founder building AI-native business tooling for SMEs.
|
||||||
|
Everything here was built incrementally while running actual client projects.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*MIT License — see LICENSE*
|
||||||
|
|
|
||||||
58
docs/deployment.md
Normal file
58
docs/deployment.md
Normal file
|
|
@ -0,0 +1,58 @@
|
||||||
|
# Deployment guide
|
||||||
|
|
||||||
|
## Stack overview
|
||||||
|
|
||||||
|
All services run as Docker containers on a single VPS, fronted by Caddy.
|
||||||
|
Authentik provides SSO with forward_auth — no per-service login required.
|
||||||
|
|
||||||
|
## Minimum VPS spec
|
||||||
|
|
||||||
|
| Resource | Minimum | Recommended |
|
||||||
|
|----------|---------|-------------|
|
||||||
|
| CPU | 4 vCPU | 8 vCPU |
|
||||||
|
| RAM | 8 GB | 16 GB |
|
||||||
|
| Disk | 80 GB SSD | 160 GB SSD |
|
||||||
|
| OS | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS |
|
||||||
|
|
||||||
|
## Directory layout on the VPS
|
||||||
|
|
||||||
|
```
|
||||||
|
/opt/atlas/
|
||||||
|
├── atlas-desktop/ # Atlas OS static files
|
||||||
|
├── brain/ # The Mind: brain.py, state files
|
||||||
|
├── cockpit/ # Cockpit API (Python FastAPI)
|
||||||
|
├── evolution/ # WhatsApp bridge config
|
||||||
|
├── forgejo/ # Forgejo docker-compose
|
||||||
|
├── nextcloud/ # Nextcloud docker-compose
|
||||||
|
└── secrets/ # NOT in git — env files, keys
|
||||||
|
```
|
||||||
|
|
||||||
|
## Caddy + Authentik SSO pattern
|
||||||
|
|
||||||
|
Every service uses the same forward_auth block:
|
||||||
|
|
||||||
|
```caddy
|
||||||
|
service.yourdomain.com {
|
||||||
|
forward_auth authentik-server:9000 {
|
||||||
|
uri /outpost.goauthentik.io/auth/caddy
|
||||||
|
copy_headers X-Authentik-Username X-Authentik-Name X-Authentik-Email
|
||||||
|
}
|
||||||
|
reverse_proxy localhost:PORT
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Starting order
|
||||||
|
|
||||||
|
1. Authentik (identity must be up first)
|
||||||
|
2. Caddy (depends on Authentik for forward_auth)
|
||||||
|
3. All other services (order-independent)
|
||||||
|
4. Atlas Brain / cockpit (depends on Odoo + Evolution)
|
||||||
|
|
||||||
|
## Environment variables
|
||||||
|
|
||||||
|
Create `/opt/atlas/secrets/` (not in git) with:
|
||||||
|
- `brain.env` — ANTHROPIC_API_KEY, LLM router URLs
|
||||||
|
- `odoo.env` — DB credentials
|
||||||
|
- `nextcloud.env` — DB credentials, admin password
|
||||||
|
- `evolution.env` — WhatsApp API key
|
||||||
|
- `router-secrets.env` — GROQ_API_KEY, CEREBRAS_API_KEY, OPENROUTER_API_KEY
|
||||||
46
docs/security.md
Normal file
46
docs/security.md
Normal file
|
|
@ -0,0 +1,46 @@
|
||||||
|
# Security model
|
||||||
|
|
||||||
|
## Perimeter
|
||||||
|
|
||||||
|
All HTTP traffic enters through **Caddy** which:
|
||||||
|
- Terminates TLS (Let's Encrypt, auto-renew)
|
||||||
|
- Applies rate limiting
|
||||||
|
- Logs all requests
|
||||||
|
|
||||||
|
## Authentication
|
||||||
|
|
||||||
|
**Authentik** (self-hosted) provides SSO via `forward_auth`:
|
||||||
|
- Every service route checks with Authentik before proxying
|
||||||
|
- Unauthenticated requests get a 302 to the login page — never a data response
|
||||||
|
- Sessions are JWT-based with configurable expiry
|
||||||
|
- MFA supported (TOTP, WebAuthn)
|
||||||
|
|
||||||
|
## Network isolation
|
||||||
|
|
||||||
|
- Internal services (cockpit, LLM router, DBs) bind to `127.0.0.1` only
|
||||||
|
- Admin APIs bind to the Tailscale interface (`100.x.x.x`) only
|
||||||
|
- Public internet never reaches internal ports directly
|
||||||
|
|
||||||
|
## AI agent gates
|
||||||
|
|
||||||
|
The Atlas Brain respects a policy file that hard-blocks autonomous action for:
|
||||||
|
- Any financial transaction
|
||||||
|
- Any external communication (email, WhatsApp send)
|
||||||
|
- Any self-modification (config changes, code deploy)
|
||||||
|
|
||||||
|
These always require human approval in the Control screen.
|
||||||
|
|
||||||
|
## Secrets management
|
||||||
|
|
||||||
|
- No secrets in git (`.gitignore` enforced)
|
||||||
|
- Vaultwarden (self-hosted) for human-facing passwords
|
||||||
|
- Env files on the VPS in `/opt/atlas/secrets/` (not world-readable)
|
||||||
|
- Rotation: manual — planned for automated rotation via Vault/n8n
|
||||||
|
|
||||||
|
## What to audit after forking
|
||||||
|
|
||||||
|
1. Change all default passwords (Authentik akadmin, Forgejo, etc.)
|
||||||
|
2. Rotate the Evolution API key
|
||||||
|
3. Disable Authentik user registration if not needed
|
||||||
|
4. Review Caddy rate-limit thresholds for your traffic
|
||||||
|
5. Set up Uptime Kuma alerts for all services
|
||||||
Loading…
Reference in a new issue