Week one at a new codebase.
The loneliest week in software.
Every developer knows the feeling. You join a project — or come back to your own after three months — and the codebase is a maze. Where does the auth logic live? Why is this abstraction here? What does this service actually do and who calls it? The README hasn't been updated since 2021. The docs are aspirational. The comments lie.
You either interrupt a senior colleague every 20 minutes, or you spend hours detective-working through 200,000 lines of code to answer a question that should take 10 seconds. OnboardingOS makes the codebase legible — permanently, for everyone, from day one.
Where does user authentication happen and what happens when a token expires?
Authentication is handled in src/auth/middleware.py (line 47) via JWT validation. On expiry, the TokenExpiredError is caught in the middleware and returns a 401. The token refresh flow is in src/auth/refresh.py — it calls UserService.rotate_token() which issues a new pair.
Why is the payment service calling the notification service directly? Is that intentional?
Based on git history, this was a quick fix in commit a3f91b2 (March 2023) by @sarah during an incident. The intention was to move this to an event queue — there's a TODO comment on line 134 and an open GitHub issue #447. It's technical debt, not intentional architecture.
RAG over your entire codebase
OnboardingOS ingests source files, git history, commit messages, PR descriptions, inline comments, and any documentation. Everything is chunked, embedded, and stored in a vector database. When you ask a question, it retrieves the most relevant context and generates an answer grounded in your actual code.
It knows the why, not just the what.
Git history contains decisions — why an abstraction was introduced, when a shortcut was taken, what was being fixed at 2am. By including commit messages and PR descriptions in the knowledge base, OnboardingOS can answer "why does this work this way?" — the question no documentation ever answers.
What OnboardingOS does
How it's built
Currently in development
RAG pipeline designed · Embedding strategy defined · Building ingestion layer for Python codebases first