Add README and technical docs

- README with quick start, package overview, links to docs - docs/setup.md — prerequisites, env vars, installation, running, testing - docs/architecture.md — monorepo structure, backend/frontend design - docs/api.md — full endpoint reference with permissions - docs/database.md — schema overview, migrations, multi-tenancy - docs/testing.md — test runner, suites, writing tests - Updated .env.example with all supported variables
2026-03-29 08:31:20 -05:00
parent b9f78639e2
commit 1d48f0befa
7 changed files with 599 additions and 7 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -0,0 +1,120 @@
+# Architecture
+
+## Monorepo Structure
+
+```
+forte/
+  packages/
+    shared/       @forte/shared — Zod schemas, types, business logic, utils
+    backend/      @forte/backend — Fastify API server
+    admin/        @forte/admin — Admin UI (React + Vite)
+  planning/       Domain planning docs (01-26)
+  docs/           Technical documentation
+```
+
+Managed with Turborepo and Bun workspaces. `@forte/shared` is a dependency of both `backend` and `admin`.
+
+## Backend
+
+**Fastify** API server with a plugin-based architecture.
+
+```
+src/
+  main.ts                 App entry, plugin registration, server start
+  plugins/
+    database.ts           Drizzle ORM + PostgreSQL connection
+    auth.ts               JWT auth, permission checking, inheritance
+    redis.ts              Valkey/Redis (ioredis)
+    cors.ts               CORS configuration
+    storage.ts            File storage provider registration
+    error-handler.ts      Centralized error → HTTP response mapping
+    dev-auth.ts           Dev-only auth bypass
+  routes/v1/
+    auth.ts               Register, login, password change, reset, profile
+    accounts.ts           Accounts, members, identifiers, payment methods, etc.
+    rbac.ts               Users list, roles CRUD, role assignments, permissions
+    files.ts              File upload/download/delete
+  services/
+    account.service.ts    Account + member business logic
+    rbac.service.ts       Roles, permissions, user role management
+    file.service.ts       File validation, storage, metadata
+    product.service.ts    Products + inventory
+    lookup.service.ts     Lookup table management
+    inventory.service.ts  Stock receipts, unit tracking
+  db/
+    schema/               Drizzle table definitions
+    migrations/           SQL migrations (drizzle-kit)
+    seeds/                System permission + role definitions
+  storage/
+    provider.ts           StorageProvider interface
+    local.ts              Local filesystem provider
+    s3.ts                 S3 provider (placeholder)
+  utils/
+    pagination.ts         withPagination, withSort, buildSearchCondition, paginatedResponse
+```
+
+### Request Flow
+
+1. Fastify receives request
+2. `onRequest` hook sets `companyId` from header
+3. `authenticate` preHandler verifies JWT, loads permissions, checks `is_active`
+4. `requirePermission` preHandler checks user has required permission slug
+5. Route handler validates input with Zod, calls service, returns response
+6. Error handler catches typed errors and maps to HTTP status codes
+
+### Permission Inheritance
+
+Permissions follow a hierarchy: `admin` implies `edit`, which implies `view` for the same domain. Having `accounts.admin` automatically grants `accounts.edit` and `accounts.view`. Non-hierarchical actions (`upload`, `delete`, `send`, `export`) don't cascade.
+
+## Frontend (Admin UI)
+
+**React** SPA with TanStack Router (file-based routing) and TanStack Query (data fetching).
+
+```
+src/
+  routes/
+    _authenticated.tsx       Layout with sidebar, permission-gated nav
+    _authenticated/
+      accounts/              Account list + detail pages
+      members/               Member list + detail pages
+      users.tsx              Users admin page
+      roles/                 Roles list + create/edit pages
+      profile.tsx            User profile + settings
+      help.tsx               In-app wiki
+    login.tsx                Login page
+  api/                       React Query options + mutations per domain
+  components/
+    ui/                      shadcn/ui primitives
+    shared/                  DataTable, AvatarUpload
+    accounts/                Domain-specific forms
+  stores/
+    auth.store.ts            Zustand — token, user, permissions
+    theme.store.ts           Zustand — color theme + light/dark mode
+  hooks/
+    use-pagination.ts        URL-based pagination state
+  lib/
+    api-client.ts            Fetch wrapper with JWT + error handling
+    themes.ts                Color theme definitions
+  wiki/
+    index.ts                 In-app help content
+```
+
+### State Management
+
+| Concern | Solution |
+|---------|----------|
+| Auth + permissions | Zustand store, persisted to sessionStorage |
+| Server data | TanStack Query (cache, refetch, invalidation) |
+| URL state (pagination) | TanStack Router search params |
+| Theme | Zustand store, persisted to localStorage |
+| Component state | React `useState` |
+
+## Multi-Tenancy
+
+Every domain table has a `company_id` column. All queries filter by the authenticated user's company. Location-scoped tables (inventory, transactions) additionally filter by `location_id`.
+
+## Database
+
+PostgreSQL 16 with Drizzle ORM. Migrations are generated with `bunx drizzle-kit generate` and applied with `bunx drizzle-kit migrate`. Schema files live in `packages/backend/src/db/schema/`.
+
+Key tables: `company`, `location`, `user`, `account`, `member`, `member_identifier`, `product`, `inventory_unit`, `role`, `permission`, `user_role_assignment`, `role_permission`, `file`.