# Code layout

The repository is a Bun workspace with one app per folder in `apps/`:

- `apps/web`: the forge, a Next.js app. Its `Dockerfile` builds the server image and `Dockerfile.runner` the runner's
- `apps/mobile`: the Android app, a Gradle project (see [mobile.md](mobile.md)). Its `package.json` only wraps
  `./gradlew` so the root's `bun run mobile:*` scripts can reach it
- `docs/`: this documentation; `patches/`: patches to dependencies, applied by `bun install`

The root `package.json` runs either app's scripts (`bun dev`, `bun run build`, `bun run lint`, `bun run test`,
`bun run mobile:build`, `bun run mobile:deploy`).

## The web app

Paths are relative to `apps/web`.

- `lib/db.ts`: starting and connecting to PocketBase; `pb_migrations/`: the schema
- `lib/users.ts`, `lib/auth.ts`: accounts and sessions (PocketBase auth records and tokens); `lib/totp.ts`, `lib/two-factor.ts`: two-factor authentication with an authenticator app
- `lib/repos.ts`: repository records, permissions (`repoAccess`), collaborators
- `lib/issues.ts`, `lib/issue-meta.ts`: issue tracker data and its shared vocabulary (statuses, priorities); UI in `components/issues/`
- `lib/keys.ts`, `lib/tokens.ts`: SSH keys and API tokens
- `lib/oauth.ts`, `lib/oauth-rules.ts`: the OAuth 2.1 authorization server for agents (`app/oauth/*`, `app/.well-known/*`); `lib/mcp/*`: the MCP endpoint (`app/mcp`) and its tools
- `lib/actor.ts`, `lib/agents.ts`: who acts (a person, or an agent for one), and agents that issues can be assigned to
- `lib/pulls.ts`: pull requests, reviews, threads and merging; UI in `app/[owner]/[repo]/pulls/`, `compare/` and `components/pulls/`
- `lib/branch-rules.ts`, `lib/protection.ts`, `lib/push-hooks.ts`, `lib/hook-script.ts`: branch protection, its rules, and the pre-receive hook that checks pushes
- `lib/push.ts`: what follows every change of refs (events, workflows, pull requests); `lib/events.ts`, `lib/webhooks.ts`: the event feed and webhooks; `lib/revert.ts`: undoing an agent's push
- `lib/markdown-views.ts`: pages as Markdown and `llms.txt`; `public/vectrum.mjs`: the command line
- `lib/git.ts`, `lib/git-write.ts`: reading from and committing to bare repositories
- `lib/git-http.ts`, `lib/ssh-server.ts`: git transports (started from `instrumentation.ts`)
- `lib/registry.ts`, `lib/registry-http.ts`: container registry storage and the OCI distribution API, served under `/v2`
- `lib/wiki.ts`, `lib/wiki-links.ts`: wiki pages in the wiki's git repository, and page names and `[[links]]`; UI in `app/[owner]/[repo]/wiki/` and `components/wiki/`
- `lib/releases.ts`, `lib/release-http.ts`: releases and their files, and the download, upload and source archive routes
- `lib/workflows.ts`, `lib/ci.ts`, `lib/runs.ts`, `lib/runners.ts`: workflow parsing, starting runs on push, the job queue and runner registration; `app/api/runner/*` is the runner API and `public/vectrum-runner.mjs` the runner
- `app/actions/*`: server actions, each re-checking the session and permissions
- `lib/app-api.ts`: the JSON API of the Android app (`app/api/v1`), which lives in `apps/mobile`