codebase-onboard

Topics in the source

• Codebase Onboarding
• 1. Survey (cheap, broad)
• 2. Identify the shape
• 3. Trace one real flow end to end
• 4. Output
• 5. Optional: save it

Goal: give the user an accurate mental model fast, grounded in real files — not a generic description of the framework. Run scripts/projectmap.sh from the repo root. It prints the tree (ignoring vendor dirs), manifests, scripts, and largest source files. Then read, in order: README, package.json / pyproject.toml, CLAUDE.md / AGENTS.md / CONTRIBUTING.md if present, .env.example, docker-compose.yml, CI config (.github/workflows/). Decide what kind of project it is from evidence: Framework: Next.js (app/ or pages/), Vite/React, Express/Fastify/NestJS, FastAPI, Django (manage.py, settings.py), Flask, CLI tool, library, monorepo (turbo.json, pnpm-workspace.yaml, nx.json). Entry points: main/bin in package.json, src/index.ts, server.ts, main.py, app.py, manage.py, main.py. Data layer: Prisma/Drizzle/TypeORM/Mongoose, SQLAlchemy/Django ORM, migration folders. External services: env vars and SDK imports. Pick the most central feature (or the one the user cares about) and follow it: route/handler → service/business logic → data access → response. Name the actual files and functions. One concrete trace teaches more than ten folder descriptions. Use a Mermaid diagram only if the flow has more

This is an excerpt. Refer to the complete source and its current requirements.