Folder and code structure conventions

Purpose

Open any repo and know where things are.

Next.js

src/
  app/            routes only — thin pages that call features
  features/<name>/ components, actions, queries for one feature
  components/ui/  shadcn primitives (don't edit generated files casually)
  lib/            supabase clients, utils, config
  types/          shared types; database.types.ts generated from Supabase
supabase/         migrations, seed.sql, config
docs/             ADRs, diagrams

Python

src/<package>/  tests/  scripts/  pyproject.toml  README.md

Plugins

one solution per plugin, src/, tests/, build/, installer/.

Rules

Feature folders, not type folders (features/panels/, not components/ + hooks/ + utils/ sprawl). No file over ~300 lines without a reason. Server code never imported into client components; keep "use client" at the leaves.

Owner: Matt · Last reviewed: 2026-09