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 **two-phase batch workflow**:

```
Phase 1: Commit All          Phase 2: Push All
─────────────────────        ─────────────────────
repo-a → commit ✓            repo-a → push ✓
repo-b → commit ✓            repo-b → push ✓
repo-c → no changes          repo-c → (skip)
repo-d → commit ✓            repo-d → push ✓
         ↓                            ↓
   All commits done          All pushes done
```

### Phase 1: Sloppy-Atomic Commits
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. **Do NOT push yet** - return `COMMITTED` status

### Phase 2: Batch Push
Only after ALL commits complete:
1. For each repo with `COMMITTED` status
2. Push to remote (with retry + rebase on rejection)
3. Update status to `SUCCESS` or `ERROR`

### Why Two Phases?
- **Atomic batch**: All commits happen before any push
- **Fail-safe**: If commit fails mid-way, no partial pushes
- **Consistent state**: Remote only sees complete batch updates

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