Development Standards

Engineering standards applied across all Level 147 projects. The goal is consistency — any developer should be able to read a Level 147 codebase and understand its conventions without a separate briefing.

Stack defaults

Unless a project has a specific reason to diverge:

Layer	Default
Frontend framework	Next.js (App Router) — currently 16.2
Language	TypeScript (strict mode)
Styling	Tailwind CSS v4
Components	shadcn/ui
Auth	NextAuth v5 + Authentik OIDC
Data fetching	TanStack Query v5
Validation	Zod
Database	Supabase (PostgreSQL)
CI/CD	Woodpecker CI
Container registry	Gitea (self-hosted)

Local development

npm install
cp .env.example .env.local   # fill in required vars
npm run dev

App runs at http://localhost:3000. Auth requires Authentik OIDC — for local dev without SSO, configure a local Authentik instance or mock the session via AUTH_SECRET.

File and naming conventions

Type	Path pattern
Widget components	`src/components/widgets/<name>.tsx`
API routes	`src/app/api/<resource>/route.ts`
Widget API routes	`src/app/api/widgets/<name>/route.ts`
Feature pages	`src/app/<feature>/page.tsx`
Shared UI (shadcn)	`src/components/ui/` — do not edit directly
Hooks	`src/hooks/use-<name>.ts`

Code quality principles

No premature abstraction. Three similar lines of code is better than a helper that has one edge case. Abstract when the pattern is proven, not anticipated.
No dead code. Remove unused functions, imports, and files.
No magic numbers. Named constants or CSS tokens; never inline unexplained values.
No comments explaining what the code does. Good names do that. Comments explain why when the reason isn’t obvious.
Fail loudly at boundaries. Validate at system entry points (user input, external APIs). Trust internal code and framework guarantees.

TypeScript

strict: true in tsconfig.json
No any without a comment explaining why
All API response types must be explicitly defined and validated with Zod
Never export types that are only used internally

Security rules (mandatory)

Every API route must:

Call auth() and return 401 if no session exists
Validate all input with Zod before using it
Never return raw service responses — sanitise and shape before sending to client
Never interpolate user input into shell commands

Do not call external services from the browser. Always proxy through /api/ routes. See Security Standards.

Environment variables

All secrets in .env (gitignored)
.env.example with placeholder values committed
Never put secrets in NEXT_PUBLIC_* variables
Document every variable in .env.example with a comment

Document	Covers
Git Workflow	Branching, commits, releases
Docs Site	This documentation platform
Widgets	Dashboard widget development
Security Standards	Security controls and policies