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
|
||||
|
||||
| Screen | Data |
|
||||
|--------|------|
|
||||
| Today | Daily brief, AI state |
|
||||
| Money | Bank transactions |
|
||||
| Inbox | Email + WhatsApp drafts |
|
||||
| Pipeline | CRM leads |
|
||||
| Fleet | POS terminals |
|
||||
| Control | Kill-switch, spend cap |
|
||||
| # | Screen | Live data |
|
||||
|---|--------|-----------|
|
||||
| 1 | **Today** | AI daily brief, accountability level |
|
||||
| 2 | **Money** | Bank transactions (Enable Banking) |
|
||||
| 3 | **Inbox** | Email + WhatsApp drafts, flagged items |
|
||||
| 4 | **Pipeline** | CRM leads and deal status (Odoo) |
|
||||
| 5 | **Fleet** | POS terminals, health, last-seen |
|
||||
| 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
|
||||
|
||||
Served at `https://command.atlascorporation.nl/os/` behind Authentik forward_auth.
|
||||
Cockpit APIs proxied server-side — no credentials in the browser.
|
||||
### Prerequisites
|
||||
- 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