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
This commit is contained in:
Ryan Moon
2026-03-29 08:31:20 -05:00
parent b9f78639e2
commit 1d48f0befa
7 changed files with 599 additions and 7 deletions

86
docs/database.md Normal file
View File

@@ -0,0 +1,86 @@
# Database
## Setup
PostgreSQL 16. Two databases:
| Database | Port | Usage |
|----------|------|-------|
| `forte` | 5432 | Development |
| `forte_api_test` | 5432 | API integration tests (auto-created by test runner) |
## Migrations
Migrations are managed by Drizzle Kit and live in `packages/backend/src/db/migrations/`.
```bash
cd packages/backend
# Generate a migration from schema changes
bunx drizzle-kit generate
# Apply pending migrations
bunx drizzle-kit migrate
```
Schema files: `packages/backend/src/db/schema/`
## Multi-Tenancy
All domain tables include `company_id` (uuid FK to `company`). Every query filters by the authenticated user's company. Location-scoped tables additionally include `location_id`.
## Schema Overview
### Core
| Table | Description |
|-------|-------------|
| `company` | Tenant (music store business) |
| `location` | Physical store location |
| `user` | Staff/admin user account |
### Accounts & Members
| Table | Description |
|-------|-------------|
| `account` | Billing entity (family, individual, business) |
| `member` | Individual person on an account |
| `member_identifier` | ID documents (DL, passport, school ID) |
| `payment_method` | Stored payment methods |
| `processor_link` | Payment processor integrations |
| `tax_exemption` | Tax exemption records |
### Inventory
| Table | Description |
|-------|-------------|
| `product` | Product catalog entry |
| `inventory_unit` | Individual serialized/non-serialized unit |
| `stock_receipt` | Incoming stock records |
| `category` | Product categories |
| `supplier` | Product suppliers |
| `inventory_unit_status` | Lookup: unit statuses |
| `item_condition` | Lookup: item conditions |
### RBAC
| Table | Description |
|-------|-------------|
| `permission` | System permissions (global, seeded) |
| `role` | Company-scoped roles (system + custom) |
| `role_permission` | Role-to-permission mapping |
| `user_role_assignment` | User-to-role mapping |
### Files
| Table | Description |
|-------|-------------|
| `file` | File metadata (path, type, size, entity reference) |
## Key Conventions
- UUIDs for all primary keys (`defaultRandom()`)
- `created_at` and `updated_at` timestamps with timezone on all tables
- Soft deletes via `is_active` boolean where applicable
- Auto-generated sequential numbers: `account_number` (6-digit), `member_number`
- Lookup tables support both system (immutable) and custom (company-scoped) values