Architecture

The organism's body plan. Named after the human body — not as metaphor, but as a design guide.

Current Architecture (Stage 3c — Self-Sufficiency)

Filesystem is the source of truth. Copy a folder, get an agent. Delete a folder, agent gone. No registry, no strings.

orbita-core/
├── dna.md                          ← THE GENETIC CODE (universal blueprint)
├── pulse.md                        ← Organism vital signs (auto-updated, gitignored)
│
├── agents/                         ← FRAMEWORK ZONE (ships with Orbita)
│   └── axiom/                         The only built-in agent
│       ├── dna.md
│       ├── instruction.md
│       ├── config.json                 { skills, grants, metadata }
│       └── skills/
│
├── tenant/                         ← CUSTOMER ZONE (your organism)
│   ├── README.md
│   └── agents/                        Dynamic agents — FOLDERS ARE THE AGENTS
│       └── <your-agent>/
│           ├── dna.md                  (copied from root dna.md)
│           ├── instruction.md          (what this agent does)
│           ├── config.json             { skills, grants, metadata }
│           └── skills/                 (agent-specific skill docs)
│
├── skills/                         ← CATALOG SKILLS (shared, markdown docs)
│   ├── send-message.skill.md
│   ├── create-task.skill.md
│   ├── query-org.skill.md
│   ├── schedule-reminder.skill.md
│   ├── send-to-inbox.skill.md
│   ├── add-contact.skill.md
│   ├── add-agent.skill.md               (structural)
│   ├── add-skill-to-agent.skill.md      (structural)
│   ├── list-agents.skill.md
│   ├── delegate-to-agent.skill.md
│   ├── set-mode.skill.md
│   ├── store-data.skill.md
│   ├── query-data.skill.md
│   ├── update-data.skill.md
│   ├── delete-data.skill.md
│   └── grant-collection-access.skill.md (structural)
│
├── src/                            ← CODE (the runtime that reads folders)
│   ├── index.ts                       Entry point
│   ├── cortex/agent.ts                Brain (loads DNA+skills → API call)
│   ├── pulse/heart.ts                 Heart (heartbeat + inbox polling)
│   ├── sense/ear.ts                   Ear (HTTP: /message, /talk, /xray)
│   ├── muscle/task.ts                 Muscles (task CRUD)
│   ├── nerve/inbox.ts                 Nervous System (inbox)
│   ├── bone/org.ts                    Skeleton (org contacts)
│   ├── circadian/scheduler.ts         Clock (reminders)
│   ├── memoria/
│   │   ├── state.ts                   State manager
│   │   └── data-service.ts            Generic namespaced CRUD (NEW in 3c)
│   ├── shield/                        Governance (NEW in 3b)
│   │   ├── governance.ts              Mode + audit log
│   │   └── gate.ts                    Skill gating wrapper
│   ├── genesis/                       Self-building (NEW in 3a, refactored in 3c)
│   │   ├── skill-catalog.ts
│   │   ├── build-catalog.ts
│   │   └── agent-loader.ts            Filesystem scanner (replaces DB registry)
│   ├── db/mongo.ts                    Database (embedded MongoDB)
│   ├── xray/                          Observability
│   └── tools/                         Tool IMPLEMENTATIONS (code)
│       └── (*.skill.ts files)
│
├── test/                           ← 74 tests, all passing
└── doc/                            ← This documentation

Framework vs Tenant

Framework zone (agents/, skills/, src/):

• Ships with Orbita
• Versioned with framework releases
• Same for every customer
• Never modified at runtime

Tenant zone (tenant/):

• Customer's private organism
• Created by Axiom at runtime
• Unique per deployment
• Can be gitignored OR committed (customer's choice)
• Can be backed up / exported / forked

Both zones load into the same runtime — one organism, one heartbeat, one inbox, one database. The split is physical (for git, backup, updates), not logical.

The Filesystem-First Principle

The folder IS the agent. No database registry, no sync, no strings.

Copy folder in    →  Agent exists immediately
Delete folder     →  Agent gone immediately
Edit config.json  →  Skills change on next wake
Edit instruction  →  Behavior changes on next wake
Zip a folder      →  Shareable agent package

This mirrors how Mac apps work: drag-and-drop, no installer, no registry. The TypeScript runtime (src/) is just the enabler that reads folders and runs them. Nothing about an agent is hidden in a database schema. Open any folder, read any file, you see everything.

Target Architecture (Adult)

As the organism grows, the directory structure follows the body map:

orbita-core/
├── pulse.md                          ← Auto-updated status
├── src/
│   ├── index.ts                      ← Entry point
│   ├── pulse/                        ← HEART — Heartbeat system
│   │   └── heart.ts                    keeps the organism alive
│   ├── cortex/                       ← BRAIN — Agent runtime
│   │   ├── agent.ts                    loads instruction sets
│   │   ├── runtime-api.ts              lightweight API-based execution
│   │   └── runtime-cli.ts              powerful CLI-based execution
│   ├── nerve/                        ← NERVOUS SYSTEM — Inbox & messaging
│   │   └── inbox.ts                    per-agent message queues
│   ├── muscle/                       ← MUSCLES — Task system
│   │   └── task.ts                     create, assign, track, complete
│   ├── bone/                         ← SKELETON — Org structure
│   │   └── org.ts                      contacts, roles, hierarchy
│   ├── sense/                        ← SENSES — Communication channels
│   │   ├── ear.ts                      channel router
│   │   └── channels/
│   │       ├── mock.channel.ts         web chat simulator
│   │       └── whatsapp.channel.ts     gateway API client
│   ├── memoria/                      ← MEMORY — State & sessions
│   │   └── state.ts                    short-term, working, long-term
│   ├── flow/                         ← BLOOD — Event bus / data pipeline
│   │   └── events.ts                   messages flowing between organs
│   ├── shield/                       ← SKIN — Governance & security
│   │   └── governance.ts               mode checking, permissions
│   ├── guard/                        ← HAIR — Input validation
│   │   └── filter.ts                   spam, duplicates, sanitization
│   ├── sentinel/                     ← IMMUNE SYSTEM — Self-healing
│   │   └── health.ts                   auto-restart, fallback, alerts
│   ├── circadian/                    ← CLOCK — Scheduling
│   │   └── scheduler.ts               cron, reminders, daily rhythms
│   ├── genesis/                      ← DNA — Configuration blueprints
│   │   ├── dna.ts                      export/import tenant config
│   │   └── architect.ts               the stem cell agent
│   ├── spawn/                        ← REPRODUCTION — Create new life
│   │   └── agent-factory.ts            provision agents, tenants
│   ├── skills/                       ← Modular capabilities
│   │   ├── registry.ts                 skill registration
│   │   ├── send-message.skill.ts
│   │   ├── create-task.skill.ts
│   │   ├── create-agent.skill.ts
│   │   └── ...
│   ├── pages/                        ← Ephemeral UI
│   │   ├── renderer.ts                 JSON → HTML
│   │   └── server.ts                   serve & handle actions
│   └── db/                           ← Database connection
│       └── mongo.ts                    per-agent MongoDB
├── instructions/                     ← Agent instruction sets
│   ├── architect.md
│   ├── receptionist.md
│   └── secretary.md
├── test/                             ← Proof of life at every stage
├── doc/                              ← This documentation (VitePress)
└── mock-ui/                          ← Web chat simulator

The Body Map

Body Part	Module	Purpose	Stage
Heart	pulse/	Heartbeat — keeps alive	0 ✓
Brain	cortex/	Agent runtime — thinks	1
Senses	sense/	Communication channels	1
Voice	speak/ (via skills)	Outbound messages	1
Muscles	muscle/	Task system	1
Memory	memoria/	State & sessions	1
Nervous System	nerve/	Inbox between agents	2
Skeleton	bone/	Org structure	2
Clock	circadian/	Scheduling	2
DNA	dna.md + genesis/	Genetic code + export/import	1 ✓ (defined)
Skin	shield/	Governance, Build/Fuse	3
Reproduction	spawn/	Create agents/tenants	3
Hair	guard/	Input validation	7
Immune System	sentinel/	Self-healing	7
Blood	flow/	Event bus	7

Data Flow (Current — Stage 1)

POST /message { from: "Naveen", text: "Tell Raju..." }
       │
       ▼
  [Sense/Ear]  receives HTTP request
       │
       ▼
  [Cortex/Agent]  builds system prompt:
       │           DNA + instruction.md + skills/*.md
       │           sends to Anthropic API with tools
       │
       ├──── tool_use: create_task ────► [Muscle/Task] ──► [MongoDB]
       │
       ├──── tool_use: send_message ──► [Console output]
       │
       ▼
  Response returned to HTTP caller
       │
       ▼
  [Memoria/State]  logs message to MongoDB

  Meanwhile: [Heart] beats every 5s, updates pulse.md

Data Flow (Target — Adult)

External Message (WhatsApp/Webhook)
       │
       ▼
  [Sense/Ear] ──── receive ────► [Flow/Events]
                                       │
                                       ▼
                                 [Pulse/Heart]
                                 checks inboxes
                                       │
                                       ▼
                                 [Nerve/Inbox]
                                 agent has message
                                       │
                                       ▼
                                 [Cortex/Agent]
                                 thinks, decides
                                       │
                              ┌────────┼────────┐
                              ▼        ▼        ▼
                         [Muscle]  [Sense]  [Circadian]
                         create    send     schedule
                         task      message  reminder
                              │        │        │
                              ▼        ▼        ▼
                         [Memoria]  [Gateway]  [BullMQ]
                         save       WhatsApp   delayed
                         state      out        job

Key Code

The Brain (loads DNA + skills → API call)

// src/cortex/agent.ts — buildSystemPrompt()

function buildSystemPrompt(config: AgentConfig): string {
  const parts: string[] = [];

  // 0. DNA — universal genetic code (every agent has this)
  const dnaPath = join(config.agentDir, "dna.md");
  if (existsSync(dnaPath)) parts.push(readFileSync(dnaPath, "utf-8"));

  // 1. Agent instruction (specialized behavior)
  const instructionPath = join(config.agentDir, "instruction.md");
  if (existsSync(instructionPath)) parts.push(readFileSync(instructionPath, "utf-8"));

  // 2. Root-level skills (shared across agents)
  parts.push(...loadSkillDocs(config.rootSkillsDir));

  // 3. Agent-local skills (only this agent has)
  parts.push(...loadSkillDocs(join(config.agentDir, "skills")));

  return parts.join("\n\n");
}

The system prompt is assembled from FILES, not hardcoded strings. Change a markdown file → behavior changes. No redeployment.

The Three Layers

  dna.md              → Laws that never change (protocol, lifecycle)
  instruction.md      → Who this agent is (personality, rules)
  skills/*.skill.md   → What this agent knows (when/how to use tools)
  ─────────────────────────────────────────────────────────
  src/tools/*.ts      → What actually happens (code, DB writes, API calls)

The Heartbeat

// src/pulse/heart.ts

export function startHeart(options: HeartOptions = {}): Heart {
  const { intervalMs = 5000, onBeat } = options;
  let tick = 0;
  let alive = true;

  const timer = setInterval(() => {
    tick++;
    if (onBeat) onBeat(tick);
  }, intervalMs);

  return {
    stop: () => { alive = false; clearInterval(timer); },
    getTick: () => tick,
    isBeating: () => alive,
  };
}

In future stages, onBeat will do more:

• Check agent inboxes for pending messages
• Check for overdue tasks
• Check for due reminders
• Run health checks (Sentinel)
• Update pulse.md with current status