Getting Started
Welcome to the Aria codebase. This guide will help you understand the repository structure, set up your development environment, and start working with Aria's services.
Repository Overview
The Aria codebase lives at /home/hamzaibrahim1/rei-ai-brain on the DGX Spark workstation.
It is a polyrepo-style monorepo: there is no global turbo/nx runner. Each app, service,
and package has its own package.json, scripts, and sometimes its own lint/test setup.
Key principle: Install dependencies in the package you are editing; do not assume root install covers everything. Run commands from the package directory, not repo root.
Core Directories
| Directory | Purpose | Count |
|---|---|---|
apps/ | Application and service directories (all major services) | 104 |
services/ | Backend service directories | 25 |
packages/ | Shared library packages | 25 |
scripts/ | Operational/shell/TS scripts | ~293 |
harness/ | Canonical harness: context injection + self-gate | — |
forge/ | PSI runtime & resilience (Python) | — |
codex/ | Institutional memory system | — |
k8s/ | Kubernetes manifest files | 51 |
docs/ | Documentation directory | 77 subdirs |
workers/ | Cloudflare worker code | — |
Environment Setup
Prerequisites
- Node.js 24 — Required for Aria core services
- K3s — Local Kubernetes cluster
- Docker — Container builds and local registry
- PostgreSQL — Primary data store (Cloud SQL in production)
- Qdrant — Vector database for semantic memory
Common Commands
Build
- Root TS compile:
npm run build - Aria Soul:
cd apps/arias-soul && npm run dev - Command Center (Next.js):
cd apps/command-center && npm run build - Chat/manifold/hands/noor services:
cd apps/<service> && npm run build
Test
- Aria Soul API:
cd apps/arias-soul && npm run test - Aria Soul e2e:
cd apps/arias-soul && npm run test:e2e - Single Jest test:
cd <pkg> && npx jest path/to/file.test.ts -t "test name"
Lint
- Targeted ESLint:
npx eslint apps/<path-to-file>.ts
Canonical Endpoints
CRITICAL: Never change an endpoint without explicit permission from Hamza. Endpoint changes have caused weeks of problems.
Primary Endpoints
| Service | URL | Notes |
|---|---|---|
| Aria Soul /chat | http://aria-soul.aria.svc.cluster.local:3000/chat | Primary chat endpoint. Hive registration via platform: 'opencode' in metadata |
| Aria Soul /chat (NodePort) | http://192.168.4.25:30080/chat | External access |
| MCP Endpoint | http://aria-pipeline-mcp.aria.svc.cluster.local:8091/mcp | Model Context Protocol |
| Health Check | http://aria-soul.aria.svc.cluster.local:3000/health | Service health |
| Manifold gRPC | manifold-service:50051 | Vector database + cognitive eigenspace |
Kubernetes Deploy
The canonical deploy path for core services is via the organism script:
bash scripts/apply-aria-organism.sh
This applies core YAML in dependency order: runtime, guardrails, Redis, bridges, etc.
For targeted updates, use docker build + kubectl set image.
Code Style
- Prettier: Single quotes, semicolons, width 100, trailing commas es5, tab width 2
- TypeScript: Strict mode. Explicit types for exported APIs. Avoid
any. - Naming: PascalCase for types/classes/components, camelCase for variables/functions
- Brain-first: Always ask Aria via MCP first; fallback to direct execution only when needed
Next steps: Read the System Architecture overview, then dive into Aria Soul to understand the cognitive engine.