Sidekick — Documentation

This is the internal documentation site for the Sidekick monorepo. It covers architecture decisions, implementation plans, and learning references for the technologies used.

Project

Document	Description
Architecture Overview	Why we built Sidekick the way we did — the reasoning behind key structural choices
Architecture Handover	Canonical reference for the current architecture — package structure, conventions, invariants
Implementation Plan	Phase-by-phase roadmap with completion status

Decisions

Concise records of non-obvious choices with rationale. Read these before changing anything they cover.

Document	Covers
Auth	Profile creation via Postgres trigger, session strategy
Supabase & API	Client separation, RLS, `withApiGuard`, deferred decisions
Tooling	pnpm, Turborepo, ESLint, tsup, CSS modules, `dotenv-cli`
Copy	`packages/copy` — centralised user-visible strings
Standards & Guidelines	Naming, file structure, export conventions
Error Handling & Instrumentation	`console.error` → Sentry deferral strategy

Learning References

Concept explainers for the technologies used. Aimed at someone who is building their backend and full-stack knowledge through this project.

Document	Covers
Supabase	Pooler vs direct connections, the four clients, RLS, `withRLS`, Postgres triggers, hydration mismatch
Auth	Authentication vs authorisation, JWTs, cookies, OAuth, the full Sidekick auth flow
Next.js	Server vs Client Components, route groups, `redirect` vs `push`, `force-dynamic`, the serialisation boundary
TypeScript	`moduleResolution` modes, `tsc` vs `tsup`, `--noEmit`, barrel files, named vs default exports
Tooling	pnpm flags, Turborepo task graph, `dotenv-cli`, ESLint flat config, `exports` subpaths
Packages	`exports` field, `workspace:*`, pnpm hoisting, `devDependencies` vs `peerDependencies`
Vercel	Logging as primitive instrumentation, env var split, deployment flow

Do It Yourself — Walkthroughs

Step-by-step build guides. Each walkthrough rebuilds a phase from scratch in its correct final form — no backtracking, with a “what and why” note on every step. Use these to reinforce understanding or to rebuild after resetting a branch.

Phase 0 — Foundation and Tooling

Document	Covers
Config Files Explained	Every config file in the initial skeleton and what it does
Checkpoint A	Monorepo init, pnpm workspace, Turborepo
Checkpoint B	TypeScript strict mode, shared tsconfig
Checkpoint C	ESLint with boundary enforcement
Checkpoint D	Prettier, Stylelint, CI scripts

Phase 1 — Supabase & Auth Shell

Document	Covers
Walkthrough	24 tasks: Supabase clients, Drizzle schema, RLS, proxy.ts, login/signup/dashboard, ESLint plugin, Vercel deployment

Implementation Plans (Archived)

Full pre-implementation plans saved for reference. These reflect the intended design at planning time — see the implementation plan for what was actually built.

Document	Phase
Phase 0 Plan	Foundation and tooling
Phase 1 Plan	Supabase auth shell