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). 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/orgs.ts, lib/org-roles.ts: organizations (accounts in users with kind "org"), their members' roles and invitations; UI in app/organizations/ and app/settings/organizations/
• lib/lists.ts: likes and lists of repositories; UI in app/lists/, components/repo-save.tsx (the Like and Save keys) and the profile's tabs (app/[owner]/tabs.tsx)
• 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