Developer Onboarding Assistant

An AI-native codebase understanding platform that accelerates developer ramp-up by extracting tribal knowledge, generating personalized learning paths, and maintaining living architecture documentation.

Register a repository, index it, then ask architectural questions and get answers with citations back to the code. The default configuration answers with a model running next to the service (Ollama), so no code or question leaves the deployment boundary unless you deliberately configure a hosted provider.

Run it locally

Full, copy-pasteable walkthrough — including HAP tenant provisioning, token issuance, and the first answer — is in specs/001-codebase-onboarding-assistant/quickstart.md. The short version:

Prerequisites — Node >=22 <23, pnpm 10.33.0 (corepack enable), Docker Engine with Compose v2. Postgres needs a raised shm_size before the first ingest (quickstart §4) or index builds fail under load.

pnpm install
cp .env.example .env

.env.example is the master variable reference: every variable the project reads is listed there. Three values have no default and Compose fails closed without them (quickstart §3):

# HAP_MASTER_ENCRYPTION_KEY — base64, 32 bytes
printf 'HAP_MASTER_ENCRYPTION_KEY=%s\n' \
  "$(python3 -c 'import os,base64;print(base64.b64encode(os.urandom(32)).decode())')"

# HAP_ADMIN_API_KEY — master admin credential; set it on `hap` only, never on `service`
printf 'HAP_ADMIN_API_KEY=%s\n' "$(openssl rand -hex 32)"

AUTH_CLIENT_SECRET is the third — you do not invent it. HAP issues it when you register the OIDC client while provisioning the tenant and user (quickstart §5). Then bring the stack up:

docker compose up -d --build
docker compose exec ollama ollama pull nomic-embed-text
docker compose exec ollama ollama pull qwen2.5-coder:7b

Service	Host port	Notes
`service`	8080	HTTP API; liveness `/health`, readiness `/ready`
`hap`	8000	Headless Auth Platform — issues the access tokens, applies its own migrations; its own probes are `/healthz` and `/readyz`, and only on 8000
`postgres`	54390	pgvector; the index-run queue is a table here, not Redis
`ollama`	11434	default answering + embedding provider
`redis`	63390	HAP's dependency only

Database migrations are applied by the service on startup — there is no separate migrate step, and concurrent starts are safe (advisory-lock serialized).

Configure

Answering model — MODEL_PROVIDER is one of ollama (default), openai, anthropic.
Embedding model — EMBEDDING_PROVIDER is configured independently (FR-042) and is one of ollama, openai. Blank means "use MODEL_PROVIDER if it can embed", which is correct for ollama and openai. Anthropic publishes no embeddings API, so MODEL_PROVIDER=anthropic requires an explicit EMBEDDING_PROVIDER; the service refuses to start rather than boot unable to index. Changing it after indexing changes which model produced the stored vectors — re-index.
Auth — AUTH_ISSUER, AUTH_INTROSPECTION_BASE_URL, AUTH_CLIENT_ID, AUTH_CLIENT_SECRET, AUTH_REDIRECT_URI. Every request is authenticated; there is no anonymous path.
Key custody — HAP_MASTER_ENCRYPTION_KEY encrypts secrets at rest and is not recoverable from a backup alone. Restore and rotation procedure: docs/operations.md.
No egress — docker-compose.no-egress.yml runs the stack on an internal network so the "nothing leaves the boundary" claim is verified by the test suite, not asserted.

Deploy

Self-hosting is the Compose path above. On a WBSP destination, use wbsp deploy <destination>; the platform injects DATABASE_* / REDIS_* and the demo auth client, so those never belong in a .env.<destination> file. Destinations and their example env files:

Destination	Type	What it is	Example file
`dev`	dev	local — service from your IDE, datastore in a container	`.env.dev.example`
`prod-parity`	compose	local — full stack in containers	`.env.prod-parity.example`
`standalone`	standalone	local — everything in one container	`.env.standalone.example`
`stage`	aws	cluster `staging`	`.env.stage.example`
`prod`	aws	cluster `main`	`.env.prod.example`

A .env.<destination> file supplies secret values only — one line per name declared under secrets: in wbsp.yaml. Anything else in it is a dead letter: the deploy resolves the declared references, ignores the rest, and still reports success, so a non-secret key set there silently has no effect. Per-destination non-secret config belongs in destination.<name>.env: in wbsp.yaml, which wins over the base env: map. MODEL_PROVIDER: ollama is the base default; a destination that needs a different provider overrides it there, in the manifest, not in an env file.

AUTH_CLIENT_SECRET and the hosted-provider API keys are declared by reference — a secret declared with no value fails the deploy, which is the behaviour we want.

Demo data

A fresh deployment is empty, and an empty deployment demos badly. After the migrations have run:

# Local destinations (dev / prod-parity / standalone): source the environment `wbsp deploy` wrote.
set -a && . ./.env && . ./.env.dev && set +a
node packages/scripts/seed-demo-data.mjs --destination dev --use-injected-env
node packages/scripts/seed-demo-data.mjs --destination dev --use-injected-env --purge  # undo it

# Cluster destinations: the CLI resolves the connection, and aws destinations need --yes.
node packages/scripts/seed-demo-data.mjs --destination stage --yes

The destination is mandatory and the connection is never spelled out here. For a cluster destination the script asks wbsp db url --destination <name> for it; for a local one it needs --use-injected-env, because wbsp db url only answers for a deployed database and reports "app has no database" for dev / prod-parity / standalone however database.enabled reads in wbsp.yaml. Either way the values are the platform-injected DATABASE_* ones, never a literal in this repo. Re-running updates rather than duplicates, so it is safe to run before every recording; --dry-run prints the plan and connects to nothing. Per-destination instructions: docs/operations.md.

Repository layout

Path	What lives there
`packages/service`	the one deployed component — Fastify HTTP API, auth, migrations, routes; listens on 8080
`packages/core`	shared types, Drizzle schema, provider adapters, structured error shapes
`packages/indexer`	repository → graph + vectors: tree-sitter extraction, ltree paths, index runs
`packages/qa`	question → answer or refusal: retrieval, evidence assembly, citation binding
`packages/cli`	command-line client (`config`, `repo`, `index`, `deps`, `ask`); speaks the HTTP contract, never the database
`packages/vscode-extension`	editor panel, selection capture, citation navigation; HTTP contract only
`packages/scripts`	operator scripts run against a destination's database, not part of the deployed service
`specs/001-codebase-onboarding-assistant`	spec, plan, data model, contracts, quickstart
`docs/`, `initial-research/`	operations runbook; original product research

Development commands — pnpm test (unit + contract + integration), pnpm test:evaluation, pnpm typecheck, pnpm lint, pnpm format:check.

Debugging from VS Code — .vscode/launch.json is checked in. Run the "dev: data services up" task (wbsp deploy --destination dev), start Ollama, then pick a configuration: Service: dev runs the same entrypoint the container runs, under the debugger, reading .env and .env.dev in the order the runbook sources them; Extension: AllAboard panel opens a dev-host window with the panel loaded from source; the AllAboard: service + extension panel compound runs both, so a question can be followed from the panel through retrieval to a cited answer in one session. The panel needs allaboard.deploymentUrl set to http://localhost:8080 and one AllAboard: Set Access Token — machine-scoped by design, so no repository can point the extension and your token at a host of its choosing.

Documentation

quickstart.md — clone → compose up → register → index → ask
docs/operations.md — install, deploy, demo data, key custody, no-egress verification
contracts/openapi.yaml — HTTP contract
contracts/errors.md — error codes and what each one means
PRODUCT.md — product decisions and their provenance
spec.md, plan.md — requirements and technical plan

The Problem

Developer onboarding remains one of the highest-friction, highest-cost activities in software delivery:

Tribal knowledge loss: The "why" behind architectural decisions, workarounds, and naming conventions exists only in senior engineers' heads—captured nowhere systematically
Generic documentation: Existing doc tools treat all developers as identical; a mobile developer needs different context than a backend integrator
Architectural amnesia: Teams cannot answer multi-hop questions requiring reasoning across the dependency graph ("why does payment service call inventory before order-service, and what happens if it fails?")
Staleness inevitable: Documentation goes out-of-date immediately after writing; no tool auto-detects architectural changes and updates docs
Expensive commercial tools: All codebase-aware AI assistants (Cursor $20/month, Copilot Enterprise $39/month, Cody Enterprise $59/month) are commercial; no production-grade open-source alternative exists

True cost of onboarding a developer: $25,000–$85,000 per hire. 22% of developers leave within 90 days without structured onboarding. Remote onboarding costs 10–20% more. Yet average ramp-up (time-to-10th-PR) remains 33 days as of Q1 2026.

The Opportunity

Build an AI-native assistant that:

Tribal knowledge extraction and structured capture: Analyze git blame history, PR descriptions, Slack threads (via integrations), and code comments to automatically surface and synthesize implicit knowledge into structured, searchable onboarding content. No current open-source tool addresses this at the codebase-graph level.
Interactive architecture explanation with multi-hop reasoning: Existing tools answer questions about individual files/functions but struggle with architectural questions requiring reasoning across the dependency graph. A GraphRAG-based layer over the codebase's call graph, data flow, and deployment topology could answer cross-service questions coherently—something vector-only RAG cannot.
Personalized onboarding journeys generated from first-PR analysis: No current tool generates dynamic onboarding paths tailored to what a specific developer will actually work on. AI could analyze assigned issues, team's service ownership, and incoming developer's prior experience (inferred from GitHub history or CV) to generate a prioritized "codebase tour" with targeted exercises.
Living architecture documentation that stays current: The fundamental failure of all doc tools is staleness. AI could run as a CI hook, detect when merged PRs change architectural boundaries (new service-to-service calls, new DB tables, changed API contracts), automatically update affected architecture diagrams/explanations, and open a PR for human review.
Accessible codebase Q&A without commercial subscription: All current codebase-aware AI tools are commercial SaaS. An open-source AI-native tool that developers can self-host against their own LLM endpoint (Ollama, local models, BYO API key) addresses open-source projects, cost-sensitive startups, and enterprises with data-sovereignty requirements.

Market Context

Market size: AI code assistants $5.42–$8.5B (2026) → $6.5–20B+ (2035); Developer experience/tooling segment rapidly growing
Adoption: 92.6% of developers use an AI coding assistant monthly (Stack Overflow 2025); 78% of Fortune 500 companies have AI-assisted dev in production (2026, up from 42% in 2024)
Impact: Average 3.6 hours/week time saved per developer using AI tools; ramp-up time (time-to-10th-PR) dropped from 39 days (Q4 2025) to 33 days (Q1 2026)
Buyer personas: Engineering managers at 50–500 engineer scaling companies, staff/principal engineers bearing institutional knowledge burden, remote-first/distributed teams, platform/DevEx teams focused on DORA metrics
Recent moves: CodeSee (visual codebase maps) shut down 2024 post-Atlassian acquisition; Sourcegraph raised $125M Series D; GitHub Copilot Enterprise $39/user/month (2024)

Key Features

MVP

Whole-repository code graph indexing (files, functions, classes, dependencies, call graph)
Natural-language Q&A over indexed codebase: answer architectural and implementation questions
Multi-hop reasoning: questions traversing the dependency graph across files and services
Self-hostable with bring-your-own-LLM (Ollama, OpenAI, Anthropic)—no data egress requirement
VS Code extension for in-editor codebase Q&A

v1.1 Enhancements

Tribal knowledge extraction: synthesize implicit context from git history, PR descriptions, code comments into structured documentation
Code-coupled documentation with staleness detection: docs linked to code identifiers, CI check when they drift
Personalized onboarding journey generation: role-specific codebase tour based on assigned work area
Architecture diagram generation from indexed code graph (Mermaid or PlantUML output)

Vision (Backlog)

Living documentation CI hook: automatically open documentation update PRs when architectural boundaries change
Multi-repository context for microservice-per-repo organizations
Onboarding analytics: time-to-first-PR, documentation views, Q&A patterns per new hire
Integration with collaboration tools (Slack, Confluence) to capture tribal knowledge from existing conversations

Research & References

Understanding Codebase like a Professional (2025): "Human–AI Collaboration for Code Comprehension" — arxiv:2504.04553
Knowledge Graph Based Repository-Level Code Generation (2025): arxiv:2505.14394
Peng et al. (2024): "Graph Retrieval-Augmented Generation: A Survey" — ACM Transactions on Information Systems
Meta Engineering (2026): "How Meta Used AI to Map Tribal Knowledge in Large-Scale Data Pipelines"
DX Research (2026): "Developer Ramp-Up Time Continues to Accelerate with AI"
McKinsey (2025): "AI Coding Tools Reduce Routine Coding Tasks by 46%" — survey of 4,500+ developers across 150 enterprises

Technology Stack Considerations

Code graph construction: Tree-sitter for AST parsing (100+ languages) + call graph analysis
Knowledge graph: GraphRAG approach with semantic embedding + entity/relationship extraction (LLM-powered)
Multi-hop reasoning: Graph-based retrieval augmented generation (GraphRAG) for dependency-aware Q&A
Tribal knowledge extraction: NLP + LLM for git blame analysis, PR description mining, code comment synthesis
Documentation generation: LLM-based architecture diagram generation (Mermaid/PlantUML) + narrative explanation
Model flexibility: Support for Ollama, OpenAI, Anthropic, or self-hosted LLM for data sovereignty

Why Now?

92.6% developer AI adoption: momentum is unstoppable; open-source alternative fills data-sovereignty/cost gap
Ramp-up time still 33 days: despite AI tooling, no product specifically addresses onboarding workflow
CodeSee shutdown: indicated consolidation into larger platforms; room for purpose-built open-source alternative
Meta + McKinsey validation: 2025–2026 peer-reviewed and industry research proving value of tribal knowledge capture
Regulatory/compliance tailwind: enterprises with IP sensitivity cannot use commercial SaaS tools; self-hosted alternative is prerequisite

Original research: initial-research/research.md, initial-research/features.md