Codebase Onboarding Generator

CODEBASE_BRIEF.md — FinTrack Platform (fintrack-platform)

Analyzer: ClearPoint Nexus — Codebase Onboarding Generator · Depth: Medium · Audience: AI-assisted session + new engineer hire

1. Repository at a Glance

2. Architecture Map

The platform follows a layered monorepo pattern with a shared internal package registry. Three applications consume shared packages; the ML pipeline is semi-isolated.

3. Tech Stack Summary

4. Key Conventions

• Environment validation: All env vars are declared and parsed with Zod in packages/config/src/env.ts. Adding an undeclared var will throw at startup. Add new vars there first.
• Database migrations: Run via pnpm db:migrate (wraps drizzle-kit migrate). Never edit migration files after they are committed — create a new one.
• API layer pattern: tRPC routers live in apps/api/src/routers/. Each domain (accounts, transactions, reports) has its own file. Shared middleware (auth guard, rate-limit) is in apps/api/src/middleware/.
• Component authorship: All UI components go in packages/ui. Do not create one-off components inside apps/web — PRs doing so are rejected at review (see CONTRIBUTING.md §3).
• Commit style: Conventional Commits enforced by commitlint + Husky pre-commit hook (.husky/, commitlint.config.ts).

5. Setup — Verified Commands

Commands verified against README.md and Makefile. Run in order.

# 1. Prerequisites: Node 20+, pnpm 8+, Docker Desktop, Python 3.11
corepack enable
corepack prepare pnpm@8.15.4 --activate

# 2. Clone and install
git clone https://github.com/example-org/fintrack-platform.git
cd fintrack-platform
pnpm install

# 3. Start infrastructure (Postgres + Redis)
docker compose up -d          # uses docker-compose.yml at repo root

# 4. Environment setup
cp .env.example .env.local    # fill in DB_URL, REDIS_URL, JWT_PRIVATE_KEY

# 5. Run migrations and seed dev data
pnpm db:migrate
pnpm db:seed                  # ⚠️ see Risk R-02 below

# 6. Start all apps in dev mode
pnpm dev                      # Turborepo runs web:3000, api:3001, worker

# 7. (Optional) Start ML service
cd ml && python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --port 50051

6. Risk Register

7. First-Week Suggested Tasks

These tasks are safe, scope-contained, and give genuine codebase exposure.

1. Fix the .env.example gap (R-02) — Add SEED_USER_EMAIL to .env.example with a placeholder value. Touches packages/db/src/seed.ts and repo root. Low risk, immediately useful, good first PR.

2. Add a pnpm typecheck script to CI — tsconfig.json files exist across all packages but no CI step runs tsc --noEmit. Add a step to .github/workflows/ci.yml. Improves type-safety feedback loop with zero production risk.

3. Write a missing tRPC router test — apps/api/src/routers/accounts.test.ts exists; transactions.test.ts does not. Write the happy-path and auth-guard tests using the existing Vitest + tRPC caller pattern in accounts.test.ts.

4. Document the analytics module — Add a README.md inside packages/analytics/ explaining the tracking destination and event schema. No code changes required; addresses R-05 and improves team knowledge retention.

5. Spike: ML service health check — Investigate adding a gRPC health probe to apps/api/src/routers/reports.ts that returns a 503 with a clear message when the ML service is unreachable (addresses R-03). Propose approach in a draft PR — no need to merge first week.

8. Gaps & Recommendations

• ⚠️ No dev environment automation — a scripts/setup.sh wrapping steps 1–6 above would eliminate the most common new-hire friction (R-01).
• ⚠️ No CODEOWNERS file — unclear who owns packages/ml-client and infra/. Add .github/CODEOWNERS.
• ℹ️ Turborepo remote cache not configured — turbo.json has no remoteCache entry. CI builds are slower than they need to be.

This brief was generated by the ClearPoint Nexus Codebase Onboarding Generator skill. All claims cite source files above. Verify anything marked ⚠️ with a team member before acting.

// codebase-brief.json (machine-readable sibling)
{
  "repo": "fintrack-platform",
  "primary_language": "TypeScript",
  "runtime": { "api": "Node 20", "ml": "Python 3.11" },
  "monorepo_tool": "Turborepo",
  "package_manager": "pnpm@8",
  "apps": [
    { "name": "web", "framework": "Next.js 14", "port": 3000 },
    { "name": "api", "framework": "Fastify 4 + tRPC", "port": 3001 },
    { "name": "worker", "framework": "BullMQ", "port": null }
  ],
  "packages": [
    { "name": "ui", "purpose": "Radix + Tailwind component library" },
    { "name": "db", "purpose": "Drizzle ORM schema and migrations" },
    { "name": "auth", "purpose": "JWT and session utilities" },
    { "name": "config", "purpose": "Shared ESLint, TS config, env schema" },
    { "name": "analytics", "purpose": "UNCLEAR — ask team", "flag": true },
    { "name": "ml-client", "purpose": "Python gRPC client wrapper for ML service" },
    { "name": "types", "purpose": "Shared Zod schemas and TypeScript types" }
  ],
  "risks": [
    { "id": "R-01", "severity": "medium", "summary": "No dev setup automation script" },
    { "id": "R-02", "severity": "high", "summary": "SEED_USER_EMAIL missing from .env.example" },
    { "id": "R-03", "severity": "medium", "summary": "No circuit breaker for ML service unavailability" },
    { "id": "R-04", "severity": "low", "summary": "No JWT rotation tooling in dev" },
    { "id": "R-05", "severity": "low", "summary": "analytics package destination not inferrable" }
  ],
  "first_week_tasks": [
    "Fix .env.example gap (R-02)",
    "Add pnpm typecheck to CI",
    "Write transactions router tests",
    "Document analytics package",
    "Spike ML service health check (R-03)"
  ],
  "setup_commands_source": "README.md + Makefile",
  "conventions_sources": ["CONTRIBUTING.md", "packages/config/src/env.ts", "commitlint.config.ts"]
}

Examples in this sample use a fictional repository (fintrack-platform) for illustration. Real client code is never included in sample outputs.

This sample illustrates the skill's output format. Names, metrics, and operational details are illustrative unless the artifact explicitly analyzes public information.