Add initial project documentation

docs/services/embedding-service.md

@@ -0,0 +1,34 @@
+# Embedding Service
+
+**Package:** `@nexusai/embedding-service`  
+**Location:** `packages/embedding-service`  
+**Deployed on:** Mini PC 1 (192.168.0.81)  
+**Port:** 3003
+
+## Purpose
+
+Converts text into vector embeddings for storage in Qdrant. Keeps
+embedding workload off the main inference node.
+
+## Dependencies
+
+- `express` — HTTP API
+- `ollama` — Ollama client for embedding model
+- `dotenv` — environment variable loading
+- `@nexusai/shared` — shared utilities
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| PORT | No | 3003 | Port to listen on |
+| OLLAMA_URL | No | http://localhost:11434 | Ollama instance URL |
+| EMBEDDING_MODEL | No | nomic-embed-text | Ollama embedding model to use |
+
+## Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| GET | /health | Service health check |
+
+> Further endpoints will be documented as the service is built out.

docs/services/inference-service.md

@@ -0,0 +1,35 @@
+# Inference Service
+
+**Package:** `@nexusai/inference-service`  
+**Location:** `packages/inference-service`  
+**Deployed on:** Main PC  
+**Port:** 3001
+
+## Purpose
+
+Thin adapter layer around the local LLM runtime (Ollama). Receives
+assembled context packages from the orchestration service and returns
+model responses.
+
+## Dependencies
+
+- `express` — HTTP API
+- `ollama` — Ollama client
+- `dotenv` — environment variable loading
+- `@nexusai/shared` — shared utilities
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| PORT | No | 3001 | Port to listen on |
+| OLLAMA_URL | No | http://localhost:11434 | Ollama instance URL |
+| DEFAULT_MODEL | No | llama3 | Default model to use for inference |
+
+## Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| GET | /health | Service health check |
+
+> Further endpoints will be documented as the service is built out.

docs/services/memory-service.md

@@ -0,0 +1,36 @@
+# Memory Service
+
+**Package:** `@nexusai/memory-service`  
+**Location:** `packages/memory-service`  
+**Deployed on:** Mini PC 1 (192.168.0.81)  
+**Port:** 3002
+
+## Purpose
+
+Responsible for all reading and writing of long-term memory. Acts as the
+sole interface to both SQLite and Qdrant — no other service accesses these
+stores directly.
+
+## Dependencies
+
+- `express` — HTTP API
+- `better-sqlite3` — SQLite driver
+- `@qdrant/js-client-rest` — Qdrant vector store client
+- `dotenv` — environment variable loading
+- `@nexusai/shared` — shared utilities
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| PORT | No | 3002 | Port to listen on |
+| SQLITE_PATH | Yes | — | Path to SQLite database file |
+| QDRANT_URL | No | http://localhost:6333 | Qdrant instance URL |
+
+## Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| GET | /health | Service health check |
+
+> Further endpoints will be documented as the service is built out.

docs/services/orchestion-service.md

@@ -0,0 +1,36 @@
+# Orchestration Service
+
+**Package:** `@nexusai/orchestration-service`  
+**Location:** `packages/orchestration-service`  
+**Deployed on:** Mini PC 2 (192.168.0.205)  
+**Port:** 4000
+
+## Purpose
+
+The main entry point for all clients. Assembles context packages from
+memory, routes prompts to inference, and writes new episodes back to
+memory after each interaction.
+
+## Dependencies
+
+- `express` — HTTP API
+- `node-fetch` — inter-service HTTP communication
+- `dotenv` — environment variable loading
+- `@nexusai/shared` — shared utilities
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| PORT | No | 4000 | Port to listen on |
+| MEMORY_SERVICE_URL | No | http://localhost:3002 | Memory service URL |
+| EMBEDDING_SERVICE_URL | No | http://localhost:3003 | Embedding service URL |
+| INFERENCE_SERVICE_URL | No | http://localhost:3001 | Inference service URL |
+
+## Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| GET | /health | Service health check |
+
+> Further endpoints will be documented as the service is built out.

docs/services/shared.md

@@ -0,0 +1,18 @@
+# Shared Package
+
+**Package:** '@nexusai/shared'
+**Location:** 'packages/shared'
+
+## Purpose
+Common utilities and configuration used across all NexusAI services
+Keeping these here avoids duplicating and ensure consistent behavior
+
+# Exports
+
+### 'getEnv(key, defaultValue?)'
+Loads an environment variable by key.  If no default is provided and the variable is missing, throws at startup rather than failing later on.
+```javascript
+const { getEnv } = require('@nexusai/shared');
+const PORT = getEnv('PORT', '3002');         // optional — falls back to 3002
+const DB   = getEnv('SQLITE_PATH');          // required — throws if missing
+```