# ARCHITECTURE.md — James Implementation Overview

James is a local-first, event-driven operations layer. Watchers emit events, agents analyze them, policy gates actions, and an optional voice layer summarizes outcomes.

---

## Data Flow

```
Nodes -> Watchers -> Redis -> Analyst/Mail -> Policy -> Action Router -> Outputs
                           |                         |
                           |                         -> Audit
                           -> Voice Stub (optional)
```

---

## Components

### Redis Backbone

- **Role:** event bus and short-term cache
- **Config:** `workspace/james/redis/redis.conf`
- **Systemd:** `workspace/james/systemd/james-redis.service`

### Watcher Agent

- **Code:** `workspace/james/agents/watcher/watcher.py`
- **Inputs:** `/proc`, Docker CLI, optional `nvidia-smi`
- **Output channel:** `james.events.system`

### Analyst Agent

- **Code:** `workspace/james/agents/analyst/analyst.py`
- **Inputs:** `james.events.system`, `james.events.mail`
- **Output channel:** `james.decisions`

### Mail Agent (dry-run)

- **Code:** `workspace/james/agents/mail/mail_agent.py`
- **Inputs:** JSON fixtures, local parsing (no live inbox)
- **Output channel:** `james.events.mail`

### Policy Engine

- **Code:** `workspace/james/agents/policy/policy_engine.py`
- **Logic:** `workspace/james/lib/policy.py`
- **Output channel:** `james.actions`

### Voice Stub

- **Code:** `workspace/james/agents/voice/voice_stub.py`
- **Inputs:** `james.actions`, `james.decisions`, `james.events.*`
- **Output channel:** `james.events.voice`

### Audit Logger

- **Code:** `workspace/james/tools/audit_logger.py`
- **Inputs:** all channels
- **Output:** JSON lines to `workspace/james/audit/audit.log`

---

## Channels

- `james.events.system` — watcher events
- `james.events.mail` — mail agent events
- `james.events.voice` — voice prompt events
- `james.decisions` — analyst decisions
- `james.actions` — policy outputs
- `james.audit` — audit replay channel

---

## Deployment Notes

- All agents are Python and run from `PYTHONPATH=<repo-root>/workspace`.
- Systemd unit files live under `workspace/james/**/systemd/`.
- Schema validation is enabled by default via `JAMES_VALIDATE_SCHEMA=1`.