Architecture

                    ┌───────────────────────── HUB (Starbase: server / AI tower / your PC) ──────────────────┐
                    │  The assistant (Celestra by default): one voice, one personality, one memory of you     │
 DEVICES            │  ┌────────────┐  ┌──────────────┐  ┌────────────┐  ┌───────────────┐  ┌──────────────┐  │
 Satellite ────────▶│  │ Gateway    │  │ Model router │  │ Agent loop │  │ Memory (Logs) │  │ Modules      │  │
 (speaker + mic)    │  │ devices,   │─▶│ + GPU/VRAM   │─▶│ tools,     │─▶│ profile, past │  │ add-ons,     │  │
 Shuttle ──────────▶│  │ web UI     │  │ scheduler    │  │ Clearance  │  │ chats, skills │  │ built-ins,   │  │
 (wall screen)      │  └────────────┘  └──────────────┘  └────────────┘  └───────────────┘  │ Mail,        │  │
 Starship ◀────────▶│        ▲         STT · TTS · chat · deep · vision · code · embeddings │ MCP tools,   │  │
 (your PC: hands)   │        │                                                              │ Beacons      │  │
 Viewscreen ───────▶│        └── Bridge (web UI, served by the hub)                         └──────────────┘  │
 (a browser)        └─────────────────────────────────────────────────────────────────────────────────────────┘

Names

Part	Name
The app	Starfarer
Hub (the main PC or server running it)	Starbase (can run always on, as a service)
UI	Bridge
The Bridge in a browser (PC, phone, tablet): nothing to install, signed in	Viewscreen
A speaker and mic in a room (Pi, mini PC): wake words on the device; music later	Satellite
A wall screen or TV with a mic and speaker, always on: the persona's hologram, a small clock, pop-ups	Shuttle
Someone's own PC or laptop (Windows, Mac, Linux): hold a key to talk, a corner window, the AI's hands there	Starship
A small ESP32 or take-along device	Probe (later)
Things added through Modules: sensors, lights, switches	Beacons (later)
Where they're paired, named and managed	the Shuttlebay deck
Extensions	Modules (from the Spacedock store)
Multi-step tasks	Away missions
Learned skills	Protocols
Memory	Logs
Permission levels	Clearance

Code map (step 1)

File	What
starfarer/config.py	Settings, data folder, the product name (one place)
starfarer/core/events.py	Event bus: everything that happens is an event anyone can listen to
starfarer/core/models.py	Model router: roles → models per hardware profile; VRAM scheduler; Ollama backend
starfarer/core/line.py	Starbase's own line in front of the brain: someone waiting goes ahead of background work
starfarer/core/systems.py	The real readings of Starbase and its devices for the AI; cutting in when something breaks; held questions
starfarer/core/persona.py	Personas (Celestra default, Computer for Guests); the locked Prime Directives, family-safe and guest rules
starfarer/core/memory.py	Logs: each person's facts, conversations and every line said; Guests per room, 30 days
starfarer/core/store.py	The one database (data/starfarer.db): WAL, versioned upgrades, merging older files
starfarer/core/security.py	Passwords, sign-in throttling, audit log, recovery codes, remote detection, HTTPS certificates (docs/SECURITY.md)
starfarer/core/crew.py	The crew: sign-in (scrypt), ranks, ages, oversight, requests to the Captain, profile suggestions
starfarer/core/chat.py	The conversation: one thread across every room and device
starfarer/hub/rings.py	Where timers, alarms and reminders ring on the room devices (where set, your own, where you were heard); a Shuttle's corner
starfarer/hub/paging.py	Paging: "page Jordan in his bedroom: ..." heard at once in that room, replies, quiet hours
starfarer/core/notify.py	Notifications: the bell, each person's settings and quiet hours, the AI catching them up (who and what kind only)
starfarer/hub/app.py	The hub's HTTP API and live WebSocket, serves the Bridge
starfarer/bridge/	The Bridge web UI: the ship's menu, Bridge (home), Comms, Logs, Engineering; readyroom.js: sign-in, Ready Room, Crew
sdk/	The Module SDK (MIT)

The Bridge's decks (the menu)

Bridge (always the landing page) · Comms · Logs · Ops (away missions) · Shuttlebay (steps 2–3) · Holodeck (step 4) · Spacedock (step 9) · Engineering (always last). Sections not built yet are listed, dimmed, with what's coming.

Personas are Ollama models

A persona's personality is its Ollama model's system prompt (baked in with a Modelfile, tested in Ollama's app). Starfarer never rewrites it. What she's sent: 1. Her model's note, word for word (if her model isn't made yet, or has no note: the persona's fallback text). 2. Optional extras from Engineering (empty by default). 3. A short context block: who she's talking to (and other names they answer to), the time, read on a screen or spoken aloud, one honesty line, and facts only when they matter for what was just said. 4. Locked rules where they apply: family-safe for Cadets and Guests, the Guest rules for Guests.

Why so little: tested on celestra-core (Nov 2026), every extra rule moved her away from her own personality.

Note swap. A model is a brain (the big weights file) plus a note and settings; Ollama stores a shared brain once on disk, but reloads it for every new model name. So if a loaded model has the same brain file, context size and chat template as the persona's model, Starfarer runs the persona on it with the persona's own note and settings: switching people and personas is instant. Build personas FROM starfarer-base (same brain, template and 32k context; see starfarer/modelfiles/) to get this; a persona on a different brain (say one on Gemma) loads its own model.

Built-in personas: Celestra (celestra-core), Nova (nova-core), Lumina (lumina-core, the teacher; she replaced Teacher), Computer (computer-core). Their Modelfiles ship in starfarer/modelfiles/; Engineering → Neural Net builds a missing one. Until its model exists, a persona says so plainly instead of answering.

Temperament and mood

Temperament is her baseline: the dials (Energy, Sarcasm, Teasing, Name use, Language, Creativity). Each persona has defaults (Engineering → Neural Net → Personas; "As built" = her model decides and nothing is added); each person can adjust theirs (Ready Room → Your AIs → Rapport with you). Language is capped per person by the Captain (Crew), and Cadets and Guests are always family-friendly.

Mood is how she feels right now, toward each person (core/mood.py): affection, irritation, excitement and concern, read from what's said (no extra model call). Insults raise irritation, more each time in a row (an argument heats up); an apology cools it fast; everything drifts back to baseline over minutes. Concern overrides anger and teasing. Only a clearly shifted mood adds a line to what she's sent. When angry she refuses favors but never anything important. Ranges: full (Celestra, Nova), caring (Lumina: warmth and concern only), off (Computer). The Bridge shows her mood, with a reset.

Mature content only when all are true: the Captain enabled it for the ship (Hub), the person is an adult by birthday and opted in (Ready Room), and they're on a private device (the Bridge, a phone) or the one device they marked as theirs. Never for Cadets or Guests. Otherwise flirting stays suggestive.

Measured on celestra-core (Nov 2026): an insult gets an edge, a second one real anger and a demand for an apology; the apology is accepted; "hey sexy" gets flirting back; "rough day" drops everything for care. Story length with the context block matches raw Ollama.

The crew

Rank	Who	Can
Captain	the owner	everything; the only one who promotes/demotes and reads conversations under oversight
First Officer	a second admin	Engineering, the Crew roster, answering Requests
Crew	adults (or a minor the Captain promoted)	their own profile, Logs, conversations, any persona
Cadet	under 18	family-safe; Lumina (settings cadet_persona), plus any others the Captain allows; no Engineering
Guest	not signed in / unknown voice	always the "Computer" persona (settings guest_persona), family-safe, nothing personal, kept 30 days

Oversight (read-only, Captain only): Cadets, anyone under 18 even if promoted (ends at 18), Guests. People under oversight are told once; Guests at the start of each conversation. Cadets become Crew on their 18th birthday. Voice (step 2): a voiceprint says who's talking (persona, Logs, name); a spoken PIN or a tap on a phone confirms anything that changes something, since a recording could fool a voiceprint.

Principles

• Windows and Linux. Python and pathlib everywhere; platform-specific bits behind small adapters.
• Local only. No cloud models.
• Shared GPU. The router only unloads models it loaded itself.
• Clearance: free (read and look), ask first (anything that changes something), never (passwords, money, permanent deletes, security settings). The assistant never grants herself abilities or permissions.
• Your memory is yours: visible, editable, deletable.

Build order

1. ✅ Hub skeleton: API + live events, model router + VRAM scheduler, persona, memory, a first Bridge.
2. Voice and the first node: hearing (Parakeet) and voice (Kokoro) as hub services; your PC's mic becomes a Starship.
3. ✅ Satellite and Shuttle on a Raspberry Pi or spare PC: wake word, mic, speaker; a Shuttle also shows the persona's hologram and things to look at on its screen (the Shuttlebay pairs and manages them).
4. Modules (manifests with signatures): the built-in ones first, then add-ons.
5. Agent, tools, MCP; ✅ Starship hands (files, commands, media keys, locking; the screen later); the AI puts things on a Shuttle and a Starship (videos).
6. Memory and learning: conversation summaries, protocols, preferences from feedback.
7. Mail & Calendar: Gmail, Google Calendar, Outlook.
8. Linux hub, hardware profiles and an installer for other people.
9. Spacedock (accounts, payments, payouts, reviews).

Sensors (the Bridge's live view)

Every piece of work is a trace: a message to her, a model download, a restart, a failed sign-in. Each trace is a chain of steps (Heard → Who → Persona → Route → Requests → Mood → Memory → Prompt → Thinking → Reply), each with a status, a time and a short summary. Summaries never contain anyone's words; the words (what was said, the prompt she was sent, her answer) are kept separately in the step's detail.

Who sees what (core/sensors.py: view(), applied to /api/sensors/traces and to every live sensors.trace event): - the person who triggered it: everything, words included - Captain / First Officer: every trace and who triggered it, every step and timing; never the words - everyone else: only their own traces

The map (hub/sensormap.py, /api/sensors/map) is rebuilt from real state on every request: installed and loaded models, which brain file each one runs on (models sharing one are listed together), which persona points at which model, connected devices, recent failures and last speeds. Each part gets a light (ok / idle / warn / error) and a reason: a failure in the last 10 minutes is red, a persona whose model isn't installed is yellow, a model under 6 tokens/s is yellow, models over the memory budget make Ollama yellow. Non-admins see only the pipeline, the personas they may use and the models those run on.

The map also carries a node graph (graph: nodes with the script and function behind each part, their inputs/outputs, and wires). The Bridge draws it ComfyUI style, always fully wired: a step lights the node whose id is its component (a model:<name> step lights that model's row, its brain node, Ollama chat and the server). Models that share one brain file share one node. The Bridge panel shows it as compact chips; enlarged, it's the full graph (pan, zoom, click a node for details; the camera follows the running node). It replaces the old Starbase and Models panels; Classic view (a button on the panel, remembered per browser) switches back to them.