Tools & Technologies

Framework

Tailwind CSS - The styling system.
shadcn/ui - Component primitives.
Radix UI - The layer backing shadcn/ui. Provides focus management, keyboard navigation, and ARIA roles without styling opinions.
Lucide React - SVG icon library.
tw-animate-css - A thin Tailwind plugin that maps animate-* utilities to CSS @keyframes, keeping animation tokens in the same layer as everything else.
clsx & tailwind-merge - clsx composes conditional class strings; tailwind-merge resolves Tailwind class conflicts so the last value wins. Both are wrapped in the cn() utility at src/utils/tailwind-merge.ts.
class-variance-authority - Type-safe variant API used by shadcn/ui components to define button, badge, and other variant sets as typed config objects rather than ad-hoc class strings.
next-themes - Handles light/dark mode.
Sonner - Toast notification library, wired in src/components/common/toast.tsx and provided at the app root for non-blocking user feedback on mutations.

Clerk - External auth provider handling sign-up, sign-in, session management, and user profiles.

Drizzle ORM - Type-safe query builder and migration runner.
PostgreSQL - The backing database via the pg driver. Runs in Docker locally; production uses the same driver pointed at a hosted provider via DATABASE_URL. Neon is the recommended production option.
Drizzle Kit - CLI companion for generating SQL migration files (pnpm db:generate) and running Drizzle Studio (pnpm db:studio).

React Hook Form - Handles form state, validation, and submission with minimal re-renders. Paired with zodResolver so the same Zod schema used by the server action also drives client-side validation.
@hookform/resolvers - Bridges React Hook Form and Zod via zodResolver. Pass it to useForm and your Zod schema becomes the validation contract for both the client form and the server action.
date-fns - Date formatting and manipulation.

Zod - Runtime validation at every boundary: route handlers, server actions, and environment variables.
T3 Env (@t3-oss/env-nextjs) - Validates all environment variables at build time using Zod.
zod-openapi - Generates an OpenAPI 3.1 spec from the same Zod schemas used for validation.
swagger-ui-dist - Serves the generated OpenAPI spec as an interactive UI at /api-docs, copied into public/ at build time via scripts/copy-swagger-ui.ts.

SWR - Handles all client-side data fetching. Every API call from the browser goes through an SWR hook in src/hooks/.
Zustand - Manages UI state that doesn't belong in a server fetch: modals, selections, ephemeral form state. Stores live in src/store/, one file per domain. See src/store/counter-store.ts for the reference shape.

Winston - All structured server-side logging via rootLogger in src/classes/loggers/application/. Every log line carries a logSource (api, action, service) so logs can be filtered by architectural layer. See Logging.
@vercel/otel - Thin wrapper around the OpenTelemetry SDK, compatible with both the Node.js and Edge runtimes. Registered in src/instrumentation.ts - Next.js calls this once on startup and all built-in spans (requests, rendering, fetch calls, route handlers) are emitted automatically. See Observability.
Jaeger - Open-source distributed tracing UI. Used locally to visualise OTel traces as waterfall diagrams. Runs via docker-compose.otel.yml alongside the OTel Collector; UI at http://localhost:16686. Not used in production - swap for Grafana, Honeycomb, or any OTLP-compatible backend by changing OTEL_EXPORTER_OTLP_ENDPOINT.

Vitest - Unit and integration test runner, configured with the jsdom environment for component tests.
React Testing Library & user-event - Renders components and queries them the way a user would. user-event simulates realistic user interactions rather than direct DOM events.
@testing-library/jest-dom - Readable Vitest matchers (toBeInTheDocument, toHaveClass, etc.), bootstrapped in vitest.setup.ts.
Playwright - End-to-end tests in e2e-tests/, covering full user flows against a running app. Run with pnpm e2e.
@clerk/testing - Official Clerk SDK for Playwright. Provides clerkSetup() (global setup) and the clerk.signIn() helper used by the role fixtures (superAdminPage, adminPage, noRolePage) to sign in via the Backend API without a password or OTP flow.

ESLint - Static analysis via flat config in eslint.config.ts. Key plugins: eslint-plugin-tsdoc (enforces TSDoc), eslint-plugin-import + simple-import-sort (import hygiene), @stylistic/eslint-plugin (comment style rules), and a local single-line-comment-style rule.
Prettier - Opinionated formatter, running on all staged files via lint-staged.
Husky & lint-staged - Power the pre-commit hook.
Trivy - Security scanner that runs on pre-commit whenever package.json or pnpm-lock.yaml changes. Blocks commits if known vulnerabilities are flagged. Install with brew install trivy on macOS.
gitleaks - Secret scanner run in CI (gitleaks detect) to catch committed credentials, API keys, and tokens before they reach the remote.

Trivy itself has faced supply chain style attacks, so keep an eye on the GitHub Advisory Database for known vulnerabilities in your toolchain.

Fumadocs - The documentation framework powering this site.
pnpm - The package manager.
tsx - Runs TypeScript files directly without a compile step. Used by all scripts/*.ts and src/db/*.ts entry points (migrations, seed, smoke check).
TSDoc - Documentation annotation standard for TypeScript. All public symbols are documented with /** */ blocks, enforced by the ESLint tsdoc plugin on pre-commit. See Code Style for the canonical shape.
concurrently - Runs the app and docs dev servers in parallel via pnpm dev:all with colour-coded output per process.
Renovate - Automated dependency updates. Configured in renovate.json, it opens grouped PRs for outdated packages on a weekly schedule and at any time for security advisories.
dotenv - Loads .env.local for scripts running outside the Next.js context. Next.js handles .env loading natively for the app itself.
Diagrams - Python library for generating the architecture diagram as code. The definition lives in diagrams/main.py. Run with uv run python main.py from the diagrams/ directory.
uv - Fast Python package manager used solely to run the diagrams script. Handles the Python environment in diagrams/pyproject.toml without a manual venv setup.

GitHub Actions - The CI pipeline, defined in .github/workflows/ci.yml. On every push and pull request it runs lint, typecheck, tests, build, and a security scan in parallel, then Playwright e2e once they all pass.
Pull request template - .github/pull_request_template.md pre-fills every PR with Problem/Solution, verification steps, and an AI-assistance disclosure prompt.

Docker Desktop / Rancher Desktop - Both supported for running the local Postgres container. Rancher Desktop is free and works well on Apple Silicon; Docker Desktop requires a paid licence for larger teams.
Dev Containers - Lightweight Docker containers providing an isolated, reproducible environment with all dependencies preinstalled. Configuration lives in .devcontainer/ - installs Postgres 17, pnpm, uv, and all project dependencies on first start. Open in VS Code and choose Reopen in Container to get a working environment without any manual setup.