CODEBASE_BRIEF.md — FinTrack Platform (fintrack-platform)

Generated: 2026-05-14 Analyzer: ClearPoint Nexus — Codebase Onboarding Generator Depth: Medium Audience: AI-assisted session + new engineer hire

1. Repository at a Glance

| Field | Value | |---|---| | Primary Language | TypeScript (84%), Python (11%), Shell (5%) | | Runtime Targets | Node 20 (API), Python 3.11 (ML pipeline) | | Monorepo Tool | Turborepo (turbo.json) | | Package Manager | pnpm 8 (pnpm-lock.yaml) | | CI Platform | GitHub Actions (.github/workflows/) | | Deployment Target | AWS ECS + Lambda (inferred from infra/ecs-task-def.json, infra/lambda/) | | Test Frameworks | Vitest (unit), Playwright (e2e), pytest (ML) | | Source of truth | packages/ — 7 workspace packages; apps/ — 3 deployable apps |

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.

graph TD
  subgraph apps
    A[apps/web — Next.js 14 dashboard]
    B[apps/api — Fastify REST + tRPC]
    C[apps/worker — BullMQ job processor]
  end

  subgraph packages
    D[packages/ui — Radix + Tailwind component lib]
    E[packages/db — Drizzle ORM schema + migrations]
    F[packages/auth — JWT + session utilities]
    G[packages/config — shared ESLint, TS, env schema]
    H[packages/analytics — event tracking client]
    I[packages/ml-client — Python gRPC client wrapper]
    J[packages/types — shared Zod schemas + TS types]
  end

  subgraph ml
    K[ml/ — FastAPI + scikit-learn scoring service]
  end

  A --> D
  A --> F
  A --> H
  A --> J
  B --> E
  B --> F
  B --> J
  B --> I
  C --> E
  C --> J
  I --> K

Diagram scope: top-level modules only. Per-file graph omitted per brief constraints.

3. Tech Stack Summary

| Layer | Technology | Config File | |---|---|---| | Frontend | Next.js 14 (App Router) | apps/web/next.config.ts | | API | Fastify 4 + tRPC v11 | apps/api/src/server.ts | | Background Jobs | BullMQ + Redis | apps/worker/src/queue.ts | | Database | PostgreSQL 15 via Drizzle ORM | packages/db/drizzle.config.ts | | Auth | JWT (RS256) + iron-session | packages/auth/src/index.ts | | ML Service | FastAPI + scikit-learn, served via gRPC | ml/main.py, ml/proto/ | | Infrastructure | AWS ECS (API/worker), Lambda (webhooks) | infra/ | | Secrets | AWS Secrets Manager + .env.local for dev | packages/config/src/env.ts |

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

| ID | Area | Severity | Finding | |---|---|---|---| | R-01 | Onboarding tooling | Medium | No automated dev environment script (make setup or equivalent). Steps must be followed manually. Recommend creating scripts/setup.sh. | | R-02 | Seed data | High | pnpm db:seed exists but seed file (packages/db/src/seed.ts) references a SEED_USER_EMAIL env var not documented in .env.example. Will throw on first run for new devs. Ask the team or add to .env.example. | | R-03 | ML service coupling | Medium | apps/api will start but return 500 on any /reports endpoint if the ML gRPC service is not running. No circuit breaker or graceful degradation detected in apps/api/src/routers/reports.ts. | | R-04 | Secret rotation | Low | JWT_PRIVATE_KEY is loaded from .env.local in dev with no rotation tooling. Production uses Secrets Manager (confirmed via infra/ecs-task-def.json), but no rotation Lambda is present yet. Flag for security review. | | R-05 | packages/analytics purpose | Low | Module exports a track() client but destination (Segment? internal?) is not inferrable from code alone. Purpose not fully inferred from code; ask the team. |

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)
{
  "generated": "2026-05-14",
  "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"]
}