b9f78639e2
- Users page: paginated, searchable, sortable with inline roles (no N+1) - Roles page: paginated, searchable, sortable + /roles/all for dropdowns - User is_active field with migration, PATCH toggle, auth check (disabled=401) - Frontend permission checks: auth store loads permissions, sidebar/buttons conditional - Profile pictures via file storage for users and members, avatar component - Identifier images use file storage API instead of base64 - Fix TypeScript errors across admin UI - 64 API tests passing (10 new)
3.7 KiB
3.7 KiB
Forte — Project Conventions
App
- Name: Forte
- Purpose: Music store management platform (POS, inventory, rentals, lessons, repairs, accounting)
- Company: Lunarfront Tech LLC
Tech Stack
- Runtime: Bun
- Language: TypeScript (strict mode, end-to-end)
- API: Fastify with Pino JSON logging
- ORM: Drizzle ORM (PostgreSQL 16)
- Validation: Zod (shared schemas between frontend and backend)
- Queue: BullMQ (Valkey-backed)
- Cache: Valkey 8 (Redis-compatible fork)
- Monorepo: Turborepo with Bun workspaces
- Testing: bun test (built-in, uses bun:test imports)
- Linting: ESLint 9 flat config + Prettier
Package Namespace
@forte/shared— types, Zod schemas, business logic, utils@forte/backend— Fastify API server
Database
- Dev:
forteon localhost:5432 - Test:
forte_teston localhost:5432 - Multi-tenant:
company_id(uuid FK) on all domain tables for tenant isolation location_id(uuid FK) on tables that need per-location scoping (inventory, transactions, drawer)- Migrations via Drizzle Kit (
bunx drizzle-kit generate,bunx drizzle-kit migrate)
Key Entity Names
account— billing entity (family, individual, or business)member— individual person on an account (NOT "student" — renamed to support multiple adults)member.is_minor— derived from date_of_birth, controls consent/portal rules
Commands
bun run dev— start all packages in dev modebun run test— run all testsbun run lint— lint all packagesbun run format— format all files with Prettier
API Conventions
- Every endpoint that returns a list must support pagination, search, and sorting — no exceptions unless the endpoint is explicitly a lightweight lookup (see below)
?page=1&limit=25— pagination (default: page 1, 25 per page, max 100)?q=search+term— full-text search across relevant columns?sort=name&order=asc— sorting by field name, asc or desc
- List responses always return
{ data: [...], pagination: { page, limit, total, totalPages } } - Search and filtering is ALWAYS server-side, never client-side
- Use
PaginationSchemafrom@forte/shared/schemasto parse query params - Use pagination helpers from
packages/backend/src/utils/pagination.ts - Lookup endpoints (e.g.,
/roles/all,/statuses/all) are the exception — these return a flat unpaginated list for populating dropdowns/selects. Use a/allsuffix to distinguish from the paginated list endpoint for the same resource.
Frontend Table Conventions
- Every table that displays data must use the shared
DataTablecomponent (components/shared/data-table.tsx) - All tables must support: search (via
?q=), sortable columns, and server-side pagination - Use the
usePagination()hook (hooks/use-pagination.ts) — it manages page, search, and sort state via URL params - All data columns that make sense to sort by should be sortable (e.g., name, email, date, status) — don't limit to just 1-2 columns
- Sub-resource tables (e.g., members within an account, payment methods) follow the same rules — use
DataTablewith pagination, not raw<Table>with unbounded queries - Loading states should use skeleton loading (built into
DataTable), not plain "Loading..." text
Conventions
- Shared Zod schemas are the single source of truth for validation (used on both frontend and backend)
- Business logic lives in
@forte/shared, not in individual app packages - API routes are thin — validate with Zod, call a service, return result
- All financial events must be auditable (append-only audit records)
- JSON structured logging with request IDs on every log line