auto-commit-service/docs/architecture.md

# 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

The service uses a **per-repo atomic workflow**:

```
┌─────────────────────────────────────────┐
│              CYCLE LOOP                 │
├─────────────────────────────────────────┤
│  repo-a: commit → push → done           │
│  repo-b: commit → push → done           │
│  repo-c: no changes → skip              │
│  repo-d: commit → push → done           │
│                 ↓                       │
│         All repos processed             │
│                 ↓                       │
│           Sleep X seconds               │
│                 ↓                       │
│            Next cycle                   │
└─────────────────────────────────────────┘
```

### Per-Repo Processing
For each repo:
1. Check `git status --porcelain`
2. Skip if no changes
3. Get diff and send to llama-service for commit message
4. Stage all changes (`git add -A`)
5. Commit with generated message
6. **Push immediately** to remote
7. Move to next repo

### Cycle Completion
When all repos processed:
- Log summary (committed, failed, unchanged)
- Persist commit history
- Sleep for `cycle_interval_seconds` (default: 60)
- Start next cycle

### Why Per-Repo Atomic?
- **Sloppy-atomic**: Each repo is self-contained (commit+push)
- **Progress visible**: Changes appear on remote as processed
- **Fail-isolated**: One repo failing doesn't block others

## 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.