|
|
|
|
@@ -1,4 +1,4 @@
|
|
|
|
|
Forte — Music Store Management Platform
|
|
|
|
|
LunarFront — Small Business Management Platform
|
|
|
|
|
|
|
|
|
|
Implementation Roadmap
|
|
|
|
|
|
|
|
|
|
@@ -8,23 +8,23 @@ Version 1.0 | Draft
|
|
|
|
|
|
|
|
|
|
# 1. Purpose
|
|
|
|
|
|
|
|
|
|
This document defines the phased implementation order for Forte — a music store management platform built by Lunarfront Tech LLC. Each phase builds on the previous, produces independently testable output, and is scoped for a solo developer working in 2-4 week increments. The goal is a working POS as early as possible, then layer on domain complexity.
|
|
|
|
|
This document defines the phased implementation order for LunarFront — a music store management platform built by Lunarfront Tech LLC. Each phase builds on the previous, produces independently testable output, and is scoped for a solo developer working in 2-4 week increments. The goal is a working POS as early as possible, then layer on domain complexity.
|
|
|
|
|
|
|
|
|
|
Tech stack: TypeScript / Bun / Fastify / Drizzle ORM / Zod / BullMQ / PostgreSQL 16 / Valkey 8 / Turborepo monorepo. See `17_Backend_Technical_Architecture.md` for full stack details.
|
|
|
|
|
|
|
|
|
|
## 1.1 Project Conventions
|
|
|
|
|
|
|
|
|
|
Name | Value
|
|
|
|
|
App name | Forte
|
|
|
|
|
Package namespace | `@forte/shared`, `@forte/backend`, etc.
|
|
|
|
|
App name | LunarFront
|
|
|
|
|
Package namespace | `@lunarfront/shared`, `@lunarfront/backend`, etc.
|
|
|
|
|
Database (dev) | `forte`
|
|
|
|
|
Database (test) | `forte_test`
|
|
|
|
|
Database (test) | `lunarfront_test`
|
|
|
|
|
Logging | JSON structured logging via Pino (Fastify built-in)
|
|
|
|
|
Linting | ESLint + Prettier at monorepo root
|
|
|
|
|
Auth (Phase 1-2) | Dev bypass via `X-Dev-User` header — JWT planned, wired in Phase 2
|
|
|
|
|
Auth (Phase 2+) | Self-issued JWTs + bcrypt, swap to Clerk/Auth0 later
|
|
|
|
|
Request tracing | Auto-generated request IDs via Fastify (included from Phase 1)
|
|
|
|
|
Test strategy | Separate `forte_test` database, reset between test runs
|
|
|
|
|
Test strategy | Separate `lunarfront_test` database, reset between test runs
|
|
|
|
|
Dev ports | API: 8000, Postgres: 5432, Valkey: 6379 (all exposed to host for dev tooling)
|
|
|
|
|
Multi-tenant | `company_id` on all tables for tenant scoping, `location_id` where per-location tracking needed (inventory, transactions, drawer, delivery)
|
|
|
|
|
|
|
|
|
|
@@ -74,18 +74,18 @@ Area | Files / Artifacts
|
|
|
|
|
Root config | `turbo.json`, root `package.json` (workspaces), `tsconfig.base.json`, `.env.example`, `CLAUDE.md`
|
|
|
|
|
Linting | `.eslintrc.cjs`, `.prettierrc`, root lint/format scripts in Turborepo pipeline
|
|
|
|
|
Docker | `docker-compose.dev.yml` — PostgreSQL 16 (`forte` database) + Valkey 8, ports exposed to host
|
|
|
|
|
Shared package | `packages/shared/package.json` (`@forte/shared`), `packages/shared/src/types/index.ts`, `packages/shared/src/schemas/index.ts`, `packages/shared/src/utils/currency.ts`, `packages/shared/src/utils/dates.ts`
|
|
|
|
|
Backend package | `packages/backend/package.json` (`@forte/backend`), `packages/backend/src/main.ts` (Fastify entry with Pino JSON logging + request ID tracing), `packages/backend/src/plugins/database.ts` (Drizzle connection), `packages/backend/src/plugins/redis.ts`, `packages/backend/src/plugins/error-handler.ts`, `packages/backend/src/plugins/cors.ts`, `packages/backend/src/plugins/dev-auth.ts` (dev bypass via `X-Dev-User` header), `packages/backend/src/routes/v1/health.ts`
|
|
|
|
|
Shared package | `packages/shared/package.json` (`@lunarfront/shared`), `packages/shared/src/types/index.ts`, `packages/shared/src/schemas/index.ts`, `packages/shared/src/utils/currency.ts`, `packages/shared/src/utils/dates.ts`
|
|
|
|
|
Backend package | `packages/backend/package.json` (`@lunarfront/backend`), `packages/backend/src/main.ts` (Fastify entry with Pino JSON logging + request ID tracing), `packages/backend/src/plugins/database.ts` (Drizzle connection), `packages/backend/src/plugins/redis.ts`, `packages/backend/src/plugins/error-handler.ts`, `packages/backend/src/plugins/cors.ts`, `packages/backend/src/plugins/dev-auth.ts` (dev bypass via `X-Dev-User` header), `packages/backend/src/routes/v1/health.ts`
|
|
|
|
|
Database | `packages/backend/src/db/index.ts` (client export), `packages/backend/src/db/schema/companies.ts` (company table — the tenant anchor), `packages/backend/src/db/schema/locations.ts` (location table — physical store locations), `drizzle.config.ts`
|
|
|
|
|
Seed script | `packages/backend/src/db/seed.ts` — creates a test company + location + admin user for local dev
|
|
|
|
|
Testing | `vitest.config.ts`, health endpoint integration test, `forte_test` database for test isolation
|
|
|
|
|
Testing | `vitest.config.ts`, health endpoint integration test, `lunarfront_test` database for test isolation
|
|
|
|
|
|
|
|
|
|
### Architecture Decisions Settled
|
|
|
|
|
|
|
|
|
|
- `company_id` (tenant) + `location_id` (physical store) scoping pattern established on the first domain tables
|
|
|
|
|
- Inventory and transaction tables use both `company_id` and `location_id`; other tables use `company_id` only
|
|
|
|
|
- Drizzle migration workflow (generate → migrate)
|
|
|
|
|
- Shared package import convention (`@forte/shared`)
|
|
|
|
|
- Shared package import convention (`@lunarfront/shared`)
|
|
|
|
|
- Standardized error response format (consistent JSON shape for errors)
|
|
|
|
|
- Request context pattern (`companyId`, `locationId`, and `user` on request)
|
|
|
|
|
- JSON structured logging via Pino with request ID on every log line
|
|
|
|
|
|