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

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.