atlus/ATLUS_CONTEXT.md

Atlus — Project Context

What Is Atlus?

Atlus is a lightweight, web-based desktop environment designed for headless single-board computers (SBCs) such as the Orange Pi, Raspberry Pi, and similar ARM-based Linux systems. It provides a browser-accessible interface that replaces the need for SSH or VNC for everyday system management tasks.

The goal is not to replicate a full desktop environment — it is to provide the right tools for managing a headless SBC in a way that feels natural, fast, and accessible from any device on the local network.

---

Problem Statement

Headless SBCs are increasingly used as always-on servers, astrophotography rigs, NAS boxes, home automation hubs, and more. Current management options are:

• SSH — powerful but unfriendly for non-developers and tedious for routine tasks
• VNC / noVNC — requires a full desktop environment, heavy, slow, not purpose-built
• Cockpit / Webmin — generic server admin tools, not tailored to SBC use cases, complex UI

There is no lightweight, purpose-built web desktop for SBCs that feels like an OS rather than a server admin panel.

---

Core Philosophy

• Web-native first — no X server required for core functionality
• Purposefully minimal — only the tools that matter for headless SBC management
• Locally hosted — runs entirely on the SBC, no cloud dependency
• Accessible from anything — phone, tablet, laptop — any browser on the local network
• Tiling over floating — apps open in the center stage, not as draggable windows
• Extensible — apps/widgets can be added as plugins

---

Target Users

• Makers and hobbyists running headless SBCs for specific purposes (astrophotography, NAS, IoT, etc.)
• Home lab users who want lightweight management without full desktop overhead
• Anyone who currently lives in SSH and wishes there was something better

---

✅ Finalized Layout — Three-Column Shell

The Atlus UI is a fixed three-column layout inspired by tiling window managers (awesomewm, i3). There are no draggable or floating windows. Everything is tiled, cascaded, or tabbed within the center stage.

┌────────┬─────────────────────────────┬────────────────┐
│        │  Stage Tab Bar              │                │
│  Left  ├─────────────────────────────┤  Right Panel   │
│  Dock  │                             │                │
│        │     Center Stage            │  - Hostname    │
│ App    │     (active app view)       │  - Date/Time   │
│ Icons  │                             │  - Network     │
│        │     One app at a time,      │  - CPU/RAM/    │
│ (vert) │     or tiled side-by-side   │    Disk/Temp   │
│        │                             │  - Services    │
│ Gear   ├─────────────────────────────┤    (toggles +  │
│ (foot) │  Layout Controls (tab bar)  │    open → )    │
└────────┴─────────────────────────────┴────────────────┘

Left Dock

• Vertical strip of app launcher icons — no labels, tooltip on hover
• Top: Atlus "A" logo — opens a system menu (shutdown, restart, about)
• Core apps listed in order (configurable in settings)
• Separator line between core apps and plugins
• Bottom: Settings gear icon (always pinned)
• Active app highlighted with accent border/background
• Badge dot on plugin icons when they have status to report (e.g. ASI Bridge syncing)

Center Stage

• The primary content area — full height, fills remaining width
• One app visible at a time by default
• Tab bar at top shows all open apps; click to switch (previous app minimizes)
• Layout toggle buttons (top-right of tab bar) switch between:
  • Single pane (full width)
  • Horizontal split (two panes side-by-side, 50/50 default)
  • Vertical split (stacked, stretch goal)
• Each pane has its own macOS-style titlebar (traffic light dots + title)
• When a second app is opened in split mode, it takes the secondary pane

Right Panel

• Always visible, fixed width (~220px), never replaced by an app
• Top section: Hostname, date, time (live), WiFi name + status, Ethernet status
• Middle section: Live system stats — CPU %, Memory used/total, Storage %, CPU temp
  • Each stat: compact uppercase label + current value + colored progress bar
  • Colors: green (healthy), amber (moderate), red (high)
• Bottom section: Services list
  • Each service: toggle (on/off), name, ↗ open button
  • Toggle maps to systemctl start/stop
  • ↗ opens that service's detail/control view in the center stage
  • Services list is configurable per deployment

---

Architecture Overview

Backend Daemon

• Language: Python (FastAPI + asyncio)
• Runs as a systemd service on boot
• Exposes a REST API and WebSocket endpoint
• Responsibilities:
  • File system access and management
  • Systemd service control (start/stop/restart/status)
  • Process/task enumeration
  • System stats (CPU, RAM, disk, network, temperature) via psutil
  • Notification/event bus (watches logs, mount points, service states)
  • X11 app process spawner (Xvfb + x11vnc per app — Phase 4 only)

Frontend

• Language: Vanilla JS + CSS (no framework — keep it lightweight and portable)
• No build step — served directly as static files by the FastAPI backend
• Communicates via REST for actions, WebSocket for live stat updates
• CSS custom properties for theming
• IBM Plex Mono for system data; Inter for UI chrome

X11 App Embedding (Phase 4 — Optional/Advanced)

• For GUI apps that require X (e.g., Nextcloud desktop client)
• Each app spawns its own Xvfb virtual framebuffer
• x11vnc streams that framebuffer over WebSocket via noVNC
• Embedded as a pane in the center stage — not a floating window
• Isolated per-app — no shared display, no full desktop environment needed

---

Built-in Apps (Core)

⚙️ System Settings

The unified configuration hub for the SBC. Organized into sections:

• General — System name/hostname, date & time (manual or NTP), timezone
• Users — User management, password changes, add/remove users
• Security — Screen lock timeout, session timeout, auth settings
• Applications — Choose which apps appear in the dock; enable/disable on startup
• Services — Which systemd services appear in the right panel; autostart configuration
• Network — Per-interface settings (WiFi SSID/password, static IP vs DHCP, DNS); shown for all detected interfaces (eth0, wlan0, etc.)
• Storage / Automount — USB automount rules, mount point configuration, eject behavior
• About — Atlus version, system info, OS details

---

📟 Terminal

A fully functional web-based terminal. No restrictions, no simplifications — behaves identically to SSH or a local terminal session. Powered by xterm.js on the frontend and ptyprocess on the backend for a real PTY.

Custom On-Screen Keyboard (Critical)

The system keyboard (iOS/Android) is never triggered. Atlus uses its own purpose-built on-screen keyboard for all terminal input. This is non-negotiable — the native keyboard is hostile to terminal use (autocorrect, autocapitalize, no Escape, no function keys, unpredictable behavior).

How it works technically:

• The xterm.js terminal canvas is focused but never triggers a system keyboard (it is not an <input> or <textarea>)
• All key input is intercepted via the custom keyboard UI — keys send characters directly to the terminal via terminal.input(char) and escape sequences for special keys
• The terminal pane never calls .focus() on any element that would summon the system keyboard
• inputmode="none" set on any focusable elements within the terminal pane as a belt-and-suspenders measure

Custom keyboard layout — three rows:

Row 1 (special/modifier):
[ Esc ] [ Tab ] [ Ctrl ] [ Alt ] [ ` ] [ ~ ] [ | ] [ \ ] [ / ]

Row 2 (function keys, scrollable):
[ F1 ] [ F2 ] [ F3 ] [ F4 ] [ F5 ] [ F6 ] [ F7 ] [ F8 ] [ F9 ] [ F10 ] [ F11 ] [ F12 ]

Row 3 (navigation):
[ ↑ ] [ ↓ ] [ ← ] [ → ] [ Home ] [ End ] [ PgUp ] [ PgDn ] [ Del ]

Modifier key behavior:

• Ctrl, Alt are sticky — tap once to arm, next key sends the combo (e.g. Ctrl → C sends \x03)
• Armed modifier keys are visually highlighted
• Double-tap a modifier to lock it (Ctrl+lock for vim, etc.)

Standard alphanumeric input:

• A compact QWERTY layout below the special rows handles letter/number/symbol input
• Numbers row across the top of the QWERTY section
• Shift key for capitals — also sticky
• Common terminal symbols promoted to easy reach: $, #, >, -, _, .

Keyboard can be:

• Toggled show/hide via a keyboard icon button in the terminal pane titlebar
• Resized (compact vs. full) — compact shows only the special row + QWERTY condensed
• On physical keyboard connected to iPad: custom keyboard hides, physical keys work natively through xterm.js

Other terminal features:

• Full color output, cursor control, scrollback
• Resize-aware (terminal resizes with the pane, keyboard height accounted for)
• Copy: long-press selection in terminal → copy action
• Paste: paste button on keyboard toolbar injects clipboard content via terminal.input()
• Multiple terminal tabs within the terminal pane (Phase 2)

---

🗂 File Manager

Unique dual-pane design. Key characteristics:

• Single or dual folder view — toggle between one panel (full width) and two side-by-side panels
• List view only — no icon grid; each row shows: icon type indicator, filename, size, modified date, permissions
• Drag and drop — files can be dragged between panels or into folders within a panel
• Sidebar — shows filesystem tree: home, root, and all detected mounts (USB, SMB, etc.)
• Features per file/selection:
  • Preview (text, image, FITS header for astrophotography files)
  • Compress / extract (zip, tar.gz)
  • Copy, move, rename, delete
  • Properties (permissions, owner, size on disk)
• Mount management — right-click a mount point to unmount; USB devices show an eject option
• Path bar — editable breadcrumb path at the top of each panel
• No thumbnails — performance-first; list only

---

📊 Task Manager

htop-inspired, but scoped and web-native. Shows:

• Process list: PID, name, CPU %, MEM %, status, user
• Sortable columns
• Kill / signal process action
• Filter to show only Atlus-relevant processes (or toggle to show all)
• Summary bar at top: total CPU, RAM, load average — mirrors the right panel stats but with more detail
• Auto-refreshes every 2 seconds via WebSocket

---

🌐 Network Monitor

Per-interface detail view:

• Interface name, MAC, state (up/down)
• IP addresses (IPv4 + IPv6)
• Gateway, DNS servers
• Live throughput (bytes in/out per second)
• For WiFi: SSID, signal strength, frequency band

---

🔧 Settings

(see System Settings above — Settings is the dock entry point into the System Settings app)

---

Plugin Apps (Installable)

App	Dock Icon	Description
ASI Bridge	🔭	ASI Air mount status, transfer log, Nextcloud sync, session summary
Log Viewer	📝	Real-time tail of any systemd service log via WebSocket
INDI Control	(future)	INDI server management for astrophotography rigs

---

Design Language

Aesthetic

• Dark, utilitarian, refined — high-end terminal meets modern OS
• Inspired by: awesomewm, macOS terminal, Linear app
• Flat — no gradients, no heavy shadows, no decorative elements

Typography

• IBM Plex Mono — all system data, file paths, IPs, timestamps, terminal output
• Inter — UI chrome, labels, app names, navigation
• Two weights only: 400 regular, 500 medium

Color System

• Background layers (dark → light): #0d0f14 → #111318 → #161b27
• Borders: #1e2130 (structural), #2a2d36 (component-level)
• Text: #c8ccd8 (primary), #8891a8 (secondary), #4a5068 (muted), #2e3348 (ghost)
• Accent (active/selected): #6ea6f0
• Status: #3ab86a (ok/green), #e09a2a (warning/amber), #e05a4a (error/red)

Motion

• Subtle only: tab switches, service toggle state, stat bar transitions
• Status values update live via WebSocket — no manual refresh needed

---

✅ Touch-First Design — Primary Target: iPad & Tablets

Atlus is touch-first. Desktop mouse/keyboard is secondary. Every interaction must be comfortable with a finger on a tablet screen. This affects every component.

Touch Target Sizing

• Minimum tap target: 48×48px for all interactive elements (Apple HIG / Material guidelines)
• Dock icons: 56×56px minimum hit area
• File rows: minimum 48px tall
• Settings rows: minimum 48px tall
• Service toggles: at least 44px tall hit area (even if visually smaller)
• Tab bar items: minimum 44px tall
• All buttons: minimum 44px tall

No Hover Dependency

• No tooltips as primary labels — dock icons must show a label below the icon (not on hover)
• No hover-only states for anything critical
• All context menus triggered by long-press, not right-click
• Hover styles may exist as a progressive enhancement for mouse users, but never as the only way to discover functionality

Gesture Support

• Swipe left/right on the center stage to switch between open apps (like iOS app switching)
• Swipe right from left edge to reveal/toggle the dock on smaller screens
• Swipe left from right edge to reveal/toggle the right panel on smaller screens
• Long-press on files for context menu (cut, copy, rename, delete, compress, properties)
• Long-press on dock icon for app options (remove from dock, move)
• Pull down on file list to refresh directory
• Pinch to zoom in terminal and file preview — browser native

Layout Adaptations for Touch

Landscape (primary tablet orientation):

• Three-column layout as designed — dock (72px wide), stage (flex), right panel (240px)
• Dock shows icon + label underneath (not tooltip)
• All rows/items generously spaced

Portrait / Narrow screens:

• Dock collapses to a slide-in drawer (swipe from left or tap hamburger)
• Right panel collapses to a slide-in drawer (swipe from right or tap info button in tab bar)
• Center stage goes full-width
• Tab bar remains visible at top

Phone (stretch goal, not v1):

• Bottom tab bar replaces left dock
• Right panel accessible via bottom sheet

File Manager — Touch Adaptations

• Row height: 52px minimum
• Drag and drop uses touch drag (touchstart/touchmove/touchend events) not mouse drag
• Selection via long-press + drag, or tap checkbox mode
• Checkbox mode: tap a file to enter selection mode, then tap others to multi-select
• Context menu on long-press: open, preview, copy, move, rename, compress, delete
• No right-click context menu (or: right-click works as fallback for mouse users)

Terminal — Touch Adaptations

• Software keyboard appears automatically on tap
• Toolbar of common keys above the software keyboard: Escape, Tab, Ctrl, arrow keys, pipe, tilde
• Pinch to adjust font size
• Two-finger scroll for scrollback

Settings — Touch Adaptations

• All form rows 52px+ tall
• Toggle switches 51×31px (standard iOS-style)
• Sidebar nav items 48px tall minimum
• Save/cancel buttons large and thumb-reachable (bottom of content, full-width or right-aligned with generous padding)

Right Panel — Touch Adaptations

• Service rows 52px tall — the toggle and ↗ button are both easy targets
• On narrow screens: collapses, accessible via swipe or button

General Touch Rules

• No double-click interactions — everything single tap or long-press
• Scroll areas must be -webkit-overflow-scrolling: touch (momentum scrolling)
• touch-action set appropriately on draggable items
• Input fields: font-size: 16px minimum to prevent iOS auto-zoom on focus
• Avoid position: fixed where possible — use position: sticky for headers/toolbars
• All modals/dialogs centered and thumb-reachable, not tiny desktop-style popups

---

Astrophotography Reference Deployment

The initial real-world deployment target:

[ASI Air]  ──ethernet──▶  [Orange Pi 5 Max / Atlus]  ──nextcloud──▶  [Home Server]
192.168.10.120              192.168.10.121 (eth to ASI Air)
                            192.168.1.121  (wifi to home network)

The ASI Bridge plugin panel shows:

• ASI Air SMB mount status (connected / disconnected / error)
• Nextcloud client sync status (idle / syncing / error)
• Live transfer log (filename, size, timestamp, sync result)
• Session summary (frames captured tonight, total GB transferred)
• Quick actions: remount share, restart sync service, clear log

---

Tech Stack

Component	Technology
Backend	Python 3.11+, FastAPI, asyncio, uvicorn
WebSockets	FastAPI WebSocket
System stats	psutil
Terminal	xterm.js (frontend) + ptyprocess (backend)
File ops	Python pathlib / os
Service mgmt	subprocess + systemctl
X11 embedding	Xvfb + x11vnc + noVNC (Phase 4 only)
Frontend	Vanilla JS, CSS custom properties, no build step
Fonts	IBM Plex Mono + Inter (Google Fonts CDN or self-hosted)
Packaging	Single systemd service + install.sh bootstrap script
Target OS	Debian/Ubuntu ARM64 (DietPi, Armbian, Raspberry Pi OS)

---

Project Phases

Phase 1 — Core Shell (start here)

• Repo and project structure setup
• FastAPI backend — /api/stats endpoint (CPU, RAM, disk, temp, network IPs)
• WebSocket endpoint — push live stats every 2s
• Static frontend served by FastAPI
• Three-column shell layout (dock, stage, right panel) — HTML/CSS skeleton
• Right panel wired to live WebSocket stats + clock
• Left dock with app icons and active state
• Terminal app — xterm.js frontend + ptyprocess PTY backend
• App switching — clicking dock icon loads app into center stage

Phase 2 — File Manager + Service Control

• File Manager — directory listing, navigate, breadcrumb path, sidebar mounts
• Service Manager — list systemd units, start/stop/restart via API
• Right panel service toggles wired to real systemctl calls
• Log Viewer — real-time tail of service logs via WebSocket stream
• Split pane layout — two apps tiled side by side

Phase 3 — Plugin System + ASI Bridge

• Plugin architecture — self-contained module (backend route + frontend panel JS)
• ASI Bridge plugin — mount watcher, transfer log, Nextcloud sync status
• Settings app — configure dock items, services list, hostname display

Phase 4 — X11 App Embedding (advanced)

• Xvfb process spawner via API call
• x11vnc per-app streaming to WebSocket
• noVNC embedded as a center stage pane
• Nextcloud Qt client embedded as live X11 panel

---

✅ Finalized Project Decisions

Decision	Answer
Project type	Single monorepo — frontend served by FastAPI backend
Framing	Full desktop environment — not a server admin panel
Authentication	Username + password (session token after login)
Default port	7779
Installation	curl | bash installer script
License	GPL
Theming	Dark only for v1 — light mode planned, CSS variables structured for it from day one
Target OS	DietPi (Debian ARM64) — installer targets DietPi, Armbian, Ubuntu Server as fallbacks
Terminal sessions	Multiple — tabbed terminals within the terminal pane
Boot / login	Branded login/boot screen before the desktop loads
Filesystem access	Full — same as any desktop environment
Terminal user	Runs as the logged-in system user
Multiple clients	Yes — multiple browsers/devices can connect simultaneously, all receive live WebSocket updates
File operations	Confirm destructive actions only (delete, overwrite)
Service detection	Auto-detect all systemd services — user manages visibility in Settings
ASI Bridge when disconnected	Show disconnected badge — still openable, shows a disconnected state screen
Plugin (ASI Bridge)	Built-in from day one, bundled with Atlus core
Dock order	Hard-coded for v1, configurable in Settings v2
Right panel width	Fixed 240px for v1

---

Project Structure (Monorepo)

atlus/
├── README.md
├── LICENSE                    # GPL
├── install.sh                 # curl | bash installer
├── atlus.service              # systemd unit file template
│
├── backend/
│   ├── main.py                # FastAPI app entry point
│   ├── config.py              # Config, paths, constants
│   ├── auth.py                # Username/password auth, session tokens
│   ├── routers/
│   │   ├── stats.py           # /api/stats — CPU, RAM, disk, temp, network
│   │   ├── files.py           # /api/files — filesystem operations
│   │   ├── services.py        # /api/services — systemd management
│   │   ├── processes.py       # /api/processes — task manager
│   │   ├── terminal.py        # /api/terminal — PTY websocket
│   │   ├── settings.py        # /api/settings — read/write config
│   │   └── plugins/
│   │       └── asi_bridge.py  # ASI Air bridge plugin routes
│   ├── ws/
│   │   └── manager.py         # WebSocket connection manager (multi-client broadcast)
│   └── requirements.txt
│
├── frontend/
│   ├── index.html             # Login/boot screen
│   ├── desktop.html           # Main desktop shell
│   ├── css/
│   │   ├── variables.css      # CSS custom properties (colors, spacing, typography)
│   │   ├── shell.css          # Three-column layout
│   │   ├── dock.css
│   │   ├── panel.css
│   │   ├── stage.css
│   │   ├── keyboard.css       # Custom on-screen keyboard
│   │   └── apps/
│   │       ├── terminal.css
│   │       ├── files.css
│   │       ├── settings.css
│   │       └── tasks.css
│   ├── js/
│   │   ├── atlus.js           # Core shell, app switching, WebSocket client
│   │   ├── auth.js            # Login screen logic
│   │   ├── keyboard.js        # Custom on-screen keyboard
│   │   └── apps/
│   │       ├── terminal.js    # xterm.js + PTY integration
│   │       ├── files.js       # File manager
│   │       ├── settings.js    # Settings app
│   │       ├── tasks.js       # Task manager
│   │       ├── services.js    # Service manager
│   │       └── asi_bridge.js  # ASI Bridge plugin panel
│   └── assets/
│       └── atlus-logo.svg
│
└── plugins/                   # Future third-party plugins live here

---

Open Questions (Deferred — Not Blocking v1)

• Portrait collapse behavior: Slide-in drawers vs. bottom tab bar — decide when building responsive CSS
• Terminal keyboard quick-key row: Exact key selection — decide during keyboard build

---

Last updated: 2026-03-13 Project status: Planning complete ✅ — all decisions finalized — ready to build Phase 1