Grand Diomande Research · Full HTML Reader

Service Architecture

**Status Legend**: ✅ **Live** (production-ready) | 🚧 **Beta** (functional, incomplete) | 🔮 **Planned** (designed but not built)

Agents That Account for Themselves architecture technical paper candidate score 54 .md

Full Public Reader

Service Architecture

Status Legend: ✅ Live (production-ready) | 🚧 Beta (functional, incomplete) | 🔮 Planned (designed but not built)

System Overview

TrajectoryOS is built as a microservices architecture with clear separation of concerns:

mermaid

graph TB
    Client[Web Dashboard / Mobile]
    Gateway[API Gateway :8080]

    Client -->|HTTP/WS| Gateway

    Gateway -->|REST| Core[Trajectory Core :3003]
    Gateway -->|REST| Agent[Agent Orchestrator :3004]
    Gateway -->|REST| Bridge[Echelon Bridge :3005]

    Core -->|HTTP| SkillModel[Skill Graph Model :5001]
    Core -->|HTTP| AlignModel[Alignment Scorer :5002]
    Core -->|HTTP| GravityModel[Gravity/Mass :5003]
    Core -->|HTTP| StateModel[Life State Model :5004]

    Core -->|Query| DB[(PostgreSQL/SQLite)]
    Core -->|Query| Vector[(Vector Store)]

    Agent -->|LLM API| OpenAI[OpenAI/Anthropic]
    Agent -->|Store| Vector

    Bridge -.->|WS| Echelon[Echelon Engine]
    Bridge -->|Store| DB

    Gateway -->|Pub/Sub| Redis[(Redis)]
    Core -->|Pub/Sub| Redis
    Agent -->|Pub/Sub| Redis

    style Echelon stroke-dasharray: 5 5
    style Redis fill:#ffcccc
    style DB fill:#ccf

f
    style Vector fill:#ccf

Service Descriptions

1. API Gateway (`:8080`)

Status: 🔮 Planned - Currently requests go directly to services

Technology: Node.js + Express/Fastify
Responsibility: Unified entry point for all client requests

Features:
- REST API proxying to backend services
- WebSocket server for real-time updates
- Authentication (JWT validation)
- Rate limiting
- Request logging

Endpoints:

GET  /health              → Health check
POST /auth/login          → User authentication
POST /auth/refresh        → Token refresh

/api/trajectory/*         → Proxy to trajectory-core
/api/agent/*              → Proxy to agent-orchestrator
/api/echelon/*            → Proxy to echelon-bridge

WebSocket Events:
- `state_updated` - Life state changed
- `interview_message` - Agent sent message
- `evidence_added` - New skill evidence
- `escape_index_changed` - η crossed threshold
- `analysis_ready` - Background insights available

---

2. Trajectory Core (`:3003`)

Status: ✅ Live - Core physics, state management, and API fully functional

Technology: Node.js + TypeScript + Prisma ORM
Database: SQLite (currently used) | PostgreSQL (documented for production)
Responsibility: Core life physics engine and state management

Key Modules:

#### Domain Layer (`src/domain/`)
- `types.ts` - TypeScript interfaces for core models
- `physics.ts` - Physics computations (thrust, η, escape velocity)
- `skillGraph.ts` - Skill graph with Bayesian tracking

#### Service Layer (`src/services/`)
- `LifeStateService.ts` - State persistence and retrieval
- `SkillService.ts` - Skill graph operations
- `ProjectService.ts` - Project management
- `EvidenceService.ts` - Evidence integration

#### API Layer (`src/index.ts`)
- Express server
- REST endpoints
- Error handling
- Validation (Zod)

Key Endpoints:

# Life State
GET  /api/state/:userId              → Current life state
GET  /api/state/:userId/history      → State history
POST /api/state/:userId/update       → Manual state update

# Skills
GET  /api/skills                     → All skills
GET  /api/skills/graph               → Skill graph
POST /api/skills/:id/evidence        → Add evidence
GET  /api/skills/:id/belief          → Bayesian posterior

# Projects
GET  /api/projects/:userId           → User's projects
POST /api/projects                   → Create project
PUT  /api/projects/:id               → Update project
DELETE /api/projects/:id             → Archive project

# Physics
GET  /api/physics/:userId            → Current physics snapshot
GET  /api/physics/:userId/breakdown  → Detailed breakdown
POST /api/physics/simulate           → Scenario simulation

Integration with Python Models:
- HTTP calls to Python microservices
- Caching layer (Redis) for expensive computations
- Async job queue for batch updates

---

3. Agent Orchestrator (`:3004`)

Status: 🚧 Beta - Basic endpoints exist, LLM integration pending

Technology: Node.js + TypeScript + OpenAI/Anthropic SDK (planned)
Responsibility: LLM-powered interview and planning

Current Reality: Interview endpoints (`/start`, `/message`, `/complete`) exist and return mock responses. No actual LLM integration yet. Planned for Q1 2026.

Key Modules:

#### Agents (`src/agents/`)
- `InterviewAgent.ts` - Conversational interviewer
- `PlannerAgent.ts` - Background analysis and planning
- `EvidenceExtractor.ts` - Structured output parsing

#### Flows (`src/flows/`)
- `SkillDiscoveryFlow.ts` - Skill interview flow
- `ProjectAssessmentFlow.ts` - Project alignment flow
- `ConstraintMappingFlow.ts` - Gravity identification

#### Scheduler (`src/scheduler/`)
- `BackgroundJobs.ts` - Periodic analysis tasks
- Job queue (Bull/BullMQ)

Key Endpoints:

# Interview
POST /api/interview/start            → Start session
POST /api/interview/:id/message      → Send user message
POST /api/interview/:id/complete     → End session
GET  /api/interview/:id              → Get session details

# Background Analysis
POST /api/analysis/trigger           → Trigger analysis
GET  /api/analysis/:id               → Get results
GET  /api/analysis/:userId/latest    → Latest insights

# Planning
POST /api/plans/generate             → Generate action plan
GET  /api/plans/:userId              → User's plans
PUT  /api/plans/:id/progress         → Update progress

LLM Integration:
- Prompt templates with versioning
- Structured output (instructor library)
- Token usage tracking
- Fallback handling

---

4. Echelon Bridge (`:3005`)

Status: 🚧 Beta - Stub service with basic endpoints, integration planned Q1-Q2 2026

Technology: Node.js + TypeScript
Responsibility: Interface to Echelon engine (computational choreography integration)

Current Reality: Stub service returning mock session data. Awaiting Echelon production deployment.

Future Integration:

#### Real-Time Stream (`src/stream.ts`)
- WebSocket client to Echelon
- Signal buffering and aggregation
- Session summary generation

#### Fusion (`src/fusion.ts`)
- Map embodied signals to life physics
- Validate verbal claims
- Detect contradictions

Key Endpoints:

GET  /health                         → Status (Echelon enabled?)
GET  /sessions/:id/summary           → Session summary
POST /sessions/:id/tag               → Tag session context
GET  /sessions/:userId/untagged      → List untagged sessions

WebSocket Events (future):
- `echelon_signal` - Real-time signal from Echelon
- `session_started` - New session begun
- `session_ended` - Session completed

---

5. Python ML Models (`:5001-5004`)

Status: 🔮 Planned Q1 2026 - Currently not implemented

Technology: Python + FastAPI + NumPy/PyTorch (planned)
Responsibility: Probabilistic and ML models

Current Reality: These services do not exist yet. Physics calculations are currently done in TypeScript within Trajectory Core. The models below represent the planned architecture for offloading complex ML computations.

5.1 Skill Graph Model (`:5001`)

File: `models/skill_graph/main.py`

python

from fastapi import FastAPI
from .bayesian_model import BayesianSkillModel

app = FastAPI()
model = BayesianSkillModel()

@app.post("/update")
def update_belief(skill_id: str, evidence: SkillEvidence):
    """Update skill belief using Bayesian inference"""
    return model.update_belief(skill_id, evidence)

@app.post("/propagate")
def propagate_update(skill_id: str, graph: SkillGraph):
    """Propagate belief through graph"""
    return model.propagate(skill_id, graph)

@app.post("/sample")
def sample_posterior(skill_id: str, n_samples: int = 1000):
    """Monte Carlo sampling"""
    return model.sample_posterior(skill_id, n_samples)

5.2 Alignment Scorer (`:5002`)

File: `models/alignment/main.py`

python

@app.post("/compute")
def compute_alignment(projects: List[Project], skills: List[SkillBelief]):
    """Compute alignment score"""
    return scorer.compute_alignment(projects, skills)

@app.post("/detect-conflicts")
def detect_conflicts(projects: List[Project]):
    """Find conflicting projects"""
    return scorer.detect_conflicts(projects)

5.3 Gravity/Mass Estimator (`:5003`)

File: `models/gravity_mass/main.py`

python

@app.post("/gravity")
def estimate_gravity(constraints: List[Constraint]):
    """Estimate gravity from constraints"""
    return estimator.estimate_gravity(constraints)

@app.post("/mass")
def estimate_mass(projects: List[Project], skills: List[SkillBelief]):
    """Estimate system mass"""
    return estimator.estimate_mass(projects, skills)

5.4 Life State Model (`:5004`)

File: `models/life_state/main.py`

python

@app.post("/predict")
def predict_next_state(current: LifeState, actions: List[Action]):
    """Predict future state"""
    return dynamics.predict_next_state(current, actions)

@app.post("/escape-time")
def estimate_escape_time(current: LifeState):
    """Estimate time to η > 1"""
    return dynamics.estimate_escape_time(current)

---

6. Vector Store (`:6000`)

Status: 🔮 Planned Q1 2026 - Semantic search not yet implemented

Technology: Node.js + Pinecone/Weaviate/ChromaDB (planned)
Responsibility: Semantic memory and search

Features:
- Document embedding (OpenAI text-embedding-3)
- Vector similarity search
- Metadata filtering
- Batch operations

Endpoints:

POST /embed                          → Generate embedding
POST /store                          → Store document
POST /search                         → Semantic search
DELETE /:id                          → Delete document
GET  /stats                          → Storage statistics

---

7. Artifact Ingestor (Background Service)

Status: 🔮 Planned Q2 2026 - Document processing not yet implemented

Technology: Node.js + Bull queue (planned)
Responsibility: Process uploaded documents

Processors:
- PDF → text extraction + chunking
- Notion → API import
- Google Calendar → commitment extraction
- GitHub → code analysis

Flow:

Upload → Queue → Process → Extract → Embed → Store (Vector DB)
                      ├→ Evidence → trajectory-core
                      └→ Metadata → database

---

Client Applications

Web Dashboard (`:3000`)

Status: ✅ Live - Production web application

Technology: Next.js + React + Tailwind CSS
Deployment: Vercel / Fly.io
Responsibility: Primary user interface

Features:
- Real-time physics dashboard
- Interview conversational UI
- Skills & projects management
- Interactive scenario simulator
- Dark mode support

Integration:
- REST API calls to trajectory-core (`:3003`)
- WebSocket connection to API gateway (planned)
- JWT authentication

---

Tauri Desktop App

Status: 🔮 Planned - Starter implementation available

Technology: Rust + React + Tauri
Platforms: macOS, Windows, Linux
Responsibility: Cross-platform native desktop application

Architecture Modes:

1. Standalone Mode (Offline-First)

┌─────────────────────────────┐
│   Tauri Desktop App         │
│  ┌─────────┐  ┌──────────┐  │
│  │ React   │←→│ Rust     │  │
│  │ UI      │  │ Physics  │  │
│  └─────────┘  └──────────┘  │
│       ↓            ↓         │
│  ┌────────────────────────┐ │
│  │  Local SQLite DB       │ │
│  └────────────────────────┘ │
└─────────────────────────────┘

Features:
- ✅ Life Physics calculations (Rust implementation)
- ✅ Skills & projects management
- ✅ Local persistence (SQLite)
- ✅ Scenario simulation
- ✅ Offline-first operation
- ❌ Interview system (no LLM)
- ❌ Background analysis

Performance: ~0.2ms physics calculations (Rust), ~50MB memory

2. Hybrid Mode (Full Features)

┌─────────────────────────────┐
│   Tauri Desktop App         │
│  ┌─────────┐  ┌──────────┐  │
│  │ React   │←→│ Rust     │  │
│  │ UI      │  │ IPC      │  │
│  └─────────┘  └──────────┘  │
│       ↓            ↓         │
│  ┌────────────────────────┐ │
│  │  HTTP Client           │ │
│  └────────────────────────┘ │
└──────────────┬──────────────┘
               ↓
      [Backend Services]

Features:
- ✅ All standalone features
- ✅ Interview system (via Agent Orchestrator)
- ✅ Background analysis & insights
- ✅ Cloud sync & multi-device
- ✅ RAG++ search

Use Cases:
- Standalone: Personal use, offline-first, privacy-focused
- Hybrid: Team use, cloud sync, AI-powered features

Documentation: See [Tauri Integration Guide](../guides/tauri-integration.md)

Implementation: [`/apps/tauri-desktop/`](../../apps/tauri-desktop/)

Key Benefits vs Web:
- 6-7x faster physics calculations (Rust vs TypeScript)
- Native OS integration (notifications, system tray)
- Offline-first operation
- Lower memory footprint (50MB vs 200MB+ web stack)
- No browser overhead

---

Mobile Apps

EchelonCapture (iOS)

Status: ✅ Live - MVP functional with Strudel integration

Technology: Swift + SwiftUI + Strudel.js
Platform: iOS 17+
Responsibility: Embodied signal capture & music generation

Features:
- ✅ Motion capture (CoreMotion)
- ✅ Beat generation (heartbeat → rhythm)
- ✅ Gesture recognition
- ✅ Music synthesis (Strudel.js)
- ✅ Phrase library & composition
- 🚧 TrajectoryOS sync (planned)

Integration with TrajectoryOS (🔮 Planned Q1-Q2 2026):
- Embodied signals → Alignment estimation
- Movement patterns → Energy/Thrust metrics
- Gesture events → Life state updates
- Real-time WebSocket connection

Documentation: See [Echelon Integration](echelon_integration.md)

TrajectoryOS Mobile (Future)

Status: 🔮 Planned Q2-Q3 2026

Technology: React Native / Flutter
Platforms: iOS, Android
Responsibility: Full TrajectoryOS experience on mobile

Features (Planned):
- Life physics dashboard
- Quick skill/project updates
- Interview on-the-go
- Notifications & insights
- Sync with desktop/web

---

Data Flow Examples

Interview Flow

1. User sends message
   Dashboard → Gateway → Agent :3004

2. Agent processes
   Agent → LLM API → Extract evidence

3. Evidence stored
   Agent → Core :3003 → Database

4. State updated
   Core → Python Models → Bayesian update → Database

5. Client notified
   Core → Redis (pub) → Gateway (sub) → WebSocket → Dashboard

Background Analysis

1. Scheduled job triggers
   Cron → Agent :3004

2. Fetch user state
   Agent → Core :3003 → Database

3. Run analysis
   Agent → LLM API → Generate insights

4. Store results
   Agent → Database

5. Notify user
   Agent → Redis (pub) → Gateway → WebSocket → Dashboard

Echelon Session (Future)

1. Echelon session active
   Echelon Engine → Bridge :3005 (WebSocket)

2. Signals aggregated
   Bridge → Session summary

3. User tags session
   Dashboard → Gateway → Bridge → Database

4. Fusion with life state
   Bridge → Core :3003 → Python Fusion Model → State update

5. Physics recomputed
   Core → Physics engine → Escape index updated

---

Deployment Architecture

Development

Local machine:
- All services running via `pnpm dev`
- PostgreSQL/SQLite database
- Redis (optional, can stub)

Production

Fly.io / Railway / AWS:
- Docker containers for each service
- Managed PostgreSQL (Fly.io Postgres / AWS RDS)
- Redis (Upstash / ElastiCache)
- Vector DB (Pinecone / Weaviate Cloud)
- S3 for file uploads

Scaling Strategy

Current (MVP, <1000 users):
- Single instance per service
- Shared database
- No caching

Growth (1k-100k users):
- Horizontal scaling (multiple instances)
- Redis cache layer
- Read replicas for database
- CDN for static assets

Scale (>100k users):
- Auto-scaling groups
- Database sharding (by userId)
- Message queue (RabbitMQ/Kafka)
- Dedicated Python model cluster

---

Security & Auth

Authentication Flow

1. User logs in
   Dashboard → Gateway → /auth/login

2. Verify credentials
   Gateway → Database (check user)

3. Generate tokens
   Gateway → JWT access token (15min) + refresh token (7 days)

4. Return to client
   Gateway → Dashboard (store in httpOnly cookie)

5. Subsequent requests
   Dashboard → Gateway (JWT in header) → Verify → Proxy to services

Service-to-Service Auth

Each service has an API key:
- Stored in environment variable
- Passed in `X-API-Key` header
- Validated by receiving service

Data Access Control

Every request includes userId:
- Gateway extracts from JWT
- Services validate ownership before returning data
- Admin role can access all (for support)

---

Monitoring & Observability

Metrics (Prometheus)

Each service exposes `/metrics`:
- Request count, latency (p50, p95, p99)
- Error rate
- Database query time
- LLM API calls
- Memory/CPU usage

Logging (Structured JSON)

json

{
  "timestamp": "2025-11-26T19:30:00Z",
  "level": "info",
  "service": "trajectory-core",
  "requestId": "abc123",
  "userId": "user-456",
  "action": "state_updated",
  "escapeIndex": 1.05,
  "latency_ms": 42
}

Alerting

PagerDuty / Slack
Triggers:
Service down (health check fails)
Error rate > 5
Latency p95 > 1s
Database connection errors

---

Technology Choices

Component	Technology	Why
Core Services	Node.js + TypeScript	Fast, type-safe, great ecosystem
ML Models	Python + FastAPI	Best ML libraries, fast API framework
Database	PostgreSQL	Reliable, rich query language, good ORM support
Vector DB	Pinecone	Managed, fast, easy integration
LLM	OpenAI GPT-4	Best quality for evidence extraction
Queue	Bull (Redis)	Simple, reliable, good monitoring
Deployment	Fly.io	Easy, global edge network, affordable

---

Next: See [Data Models](data-models.md) for database schema details.

Promotion Decision

Promote into a technical note or architecture paper with implementation anchors.

Source Anchor

Comp-Core/backend/cc-trajectory/docs/architecture/services.md

Detected Structure

Method · Evaluation · Code Anchors · Architecture