diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..d5446b3
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,124 @@
+# Auto-Commit Service Architecture
+
+## Overview
+
+The auto-commit service monitors git repositories for uncommitted changes and automatically generates commit messages using a local LLM (llama-service).
+
+## Monitoring Scope
+
+### What Gets Monitored
+
+The service monitors **git repositories**, not individual packages.
+
+| Metric | Count | Notes |
+|--------|-------|-------|
+| Git repos in @packages | 58 | Excludes node_modules |
+| Git repos in @applications | 10 | @audio, @image, @lilith, @ml |
+| **Total monitored** | **68** | |
+
+### Package vs Repo Distinction
+
+```
+@packages/                    # Workspace root
+├── @nestjs/                  # 1 git repo
+│   ├── .git/
+│   ├── auth/                 # package: @lilith/nestjs-auth
+│   ├── bootstrap/            # package: @lilith/nestjs-bootstrap
+│   └── health/               # package: @lilith/nestjs-health
+└── @eslint/
+    ├── config-base/          # 1 git repo, 1 package
+    │   └── .git/
+    └── config-react/         # 1 git repo, 1 package
+        └── .git/
+```
+
+- **114 npm packages** (`package.json` files)
+- **26 Python packages** (`pyproject.toml` files)
+- **59 git repos** (`.git` directories) - this is what gets monitored
+
+Git commits happen at the repo level, so monitoring repos (not packages) is correct.
+
+## Configured Base Paths
+
+```python
+repos_base_paths = [
+    "/var/home/lilith/Code/@packages",
+    "/var/home/lilith/Code/@applications/@audio",
+    "/var/home/lilith/Code/@applications/@image",
+    "/var/home/lilith/Code/@applications/@lilith",
+    "/var/home/lilith/Code/@applications/@ml",
+]
+```
+
+## Discovery Process
+
+1. For each base path, recursively find `.git` directories
+2. Filter out excluded patterns: `node_modules`, `.venv`, `dist`, `build`, `__pycache__`
+3. Respect `recursive_depth` limit (default: 4)
+4. Deduplicate repos found in multiple paths
+
+## Service Dependencies
+
+```
+┌─────────────────────┐
+│  auto-commit-service│ Port 8200
+│  (scheduler/daemon) │
+└─────────┬───────────┘
+          │ HTTP
+          ▼
+┌─────────────────────┐
+│   llama-service     │ Port 8000
+│   (LLM inference)   │
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│  qwen2.5-1.5b       │ ~1.1GB model
+│  (commit messages)  │
+└─────────────────────┘
+```
+
+## Cycle Flow
+
+1. **Discovery**: Find all git repos across configured base paths
+2. **Status Check**: For each repo, check `git status --porcelain`
+3. **Skip Clean**: Repos with no changes are skipped
+4. **Generate Message**: Send diff to llama-service for commit message
+5. **Commit**: Stage all changes and commit with generated message
+6. **Push**: Push to configured remote (default: origin/master)
+
+## API Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/health` | GET | Service health check |
+| `/status` | GET | Current daemon status, last cycle results |
+| `/repos` | GET | List all monitored repositories |
+| `/trigger` | POST | Manually trigger a commit cycle |
+| `/enable` | POST | Enable the daemon |
+| `/disable` | POST | Disable the daemon |
+| `/history` | GET | View commit history |
+
+## Configuration
+
+Key settings in `AutoCommitSettings`:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `cycle_interval_seconds` | 60 | Time between commit cycles |
+| `llama_model_id` | qwen2.5-1.5b-instruct | Model for commit messages |
+| `recursive_depth` | 4 | Max depth for repo discovery |
+| `git_remote` | origin | Remote to push to |
+| `git_branch` | master | Branch to push |
+
+## Related Scripts
+
+Existing scripts in `@packages/scripts/` provide similar functionality:
+
+| Script | Purpose |
+|--------|---------|
+| `git/git-repo-status.sh` | Check status across all repos |
+| `git/commit-all-dirty.sh` | Simple bulk commit (no LLM) |
+| `git/git-push-all.sh` | Push all repos |
+
+The auto-commit service is the "AI-powered" version that generates better commit messages via LLM, while the scripts provide simpler manual alternatives.