Jean-Luc Makiola
261c1f9d02
Archive roadmap, requirements, and phase directories to milestones/. Evolve PROJECT.md with validated requirements and key decisions. Reorganize ROADMAP.md with milestone grouping. Delete REQUIREMENTS.md (fresh for next milestone).
152 lines
6.0 KiB
Markdown
152 lines
6.0 KiB
Markdown
---
|
|
phase: 01-foundation-and-collection
|
|
plan: 01
|
|
subsystem: infra
|
|
tags: [vite, hono, bun, drizzle, sqlite, tanstack-router, tailwind, zod, react]
|
|
|
|
requires: []
|
|
provides:
|
|
- Project scaffold with Vite + Hono + TanStack Router + Tailwind + Drizzle
|
|
- SQLite database schema with items, categories, and settings tables
|
|
- Shared Zod validation schemas for items and categories
|
|
- TypeScript types inferred from Zod and Drizzle schemas
|
|
- In-memory SQLite test helper for isolated test databases
|
|
- Default Uncategorized category seeded on server start
|
|
affects: [01-02, 01-03, 01-04, 02-01, 02-02]
|
|
|
|
tech-stack:
|
|
added: [react@19.2, vite@8.0, hono@4.12, drizzle-orm@0.45, tailwindcss@4.2, tanstack-router@1.167, tanstack-query@5.90, zustand@5.0, zod@4.3, biome@2.4]
|
|
patterns: [vite-proxy-to-hono, bun-sqlite-wal-fk, drizzle-schema-as-code, shared-zod-schemas, file-based-routing]
|
|
|
|
key-files:
|
|
created:
|
|
- vite.config.ts
|
|
- drizzle.config.ts
|
|
- src/db/schema.ts
|
|
- src/db/index.ts
|
|
- src/db/seed.ts
|
|
- src/shared/schemas.ts
|
|
- src/shared/types.ts
|
|
- src/server/index.ts
|
|
- src/client/main.tsx
|
|
- src/client/routes/__root.tsx
|
|
- src/client/routes/index.tsx
|
|
- tests/helpers/db.ts
|
|
modified:
|
|
- package.json
|
|
- tsconfig.json
|
|
- .gitignore
|
|
|
|
key-decisions:
|
|
- "TanStack Router requires routesDirectory and generatedRouteTree config when routes are in src/client/routes instead of default src/routes"
|
|
- "Added better-sqlite3 as devDependency for drizzle-kit CLI (cannot use bun:sqlite)"
|
|
|
|
patterns-established:
|
|
- "Vite proxy pattern: frontend on 5173, Hono backend on 3000, proxy /api and /uploads"
|
|
- "Database connection: bun:sqlite with PRAGMA WAL and foreign_keys ON"
|
|
- "Shared schemas: Zod schemas in src/shared/schemas.ts used by both client and server"
|
|
- "Test isolation: in-memory SQLite via createTestDb() helper"
|
|
|
|
requirements-completed: [COLL-01, COLL-03]
|
|
|
|
duration: 4min
|
|
completed: 2026-03-14
|
|
---
|
|
|
|
# Phase 1 Plan 01: Project Scaffolding Summary
|
|
|
|
**Full-stack scaffold with Vite 8 + Hono on Bun, Drizzle SQLite schema for items/categories, shared Zod validation, and in-memory test infrastructure**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** 4 min
|
|
- **Started:** 2026-03-14T21:31:03Z
|
|
- **Completed:** 2026-03-14T21:35:06Z
|
|
- **Tasks:** 2
|
|
- **Files modified:** 15
|
|
|
|
## Accomplishments
|
|
|
|
- Complete project scaffold with all dependencies installed and Vite build passing
|
|
- SQLite database schema with items, categories, and settings tables via Drizzle ORM
|
|
- Shared Zod schemas for item and category validation used by both client and server
|
|
- In-memory SQLite test helper for isolated unit/integration tests
|
|
- Default Uncategorized category seeded on Hono server startup
|
|
|
|
## Task Commits
|
|
|
|
Each task was committed atomically:
|
|
|
|
1. **Task 1: Project scaffolding and configuration** - `67ff860` (feat)
|
|
2. **Task 2: Database schema, shared schemas, seed, and test infrastructure** - `7412ef1` (feat)
|
|
|
|
## Files Created/Modified
|
|
|
|
- `vite.config.ts` - Vite config with TanStack Router plugin, React, Tailwind, and API proxy
|
|
- `drizzle.config.ts` - Drizzle Kit config for SQLite schema management
|
|
- `tsconfig.json` - TypeScript config with path aliases and DOM types
|
|
- `package.json` - All dependencies and dev scripts
|
|
- `index.html` - Vite SPA entry point
|
|
- `biome.json` - Biome linter/formatter config
|
|
- `.gitignore` - Updated with GearBox-specific ignores
|
|
- `src/db/schema.ts` - Drizzle table definitions for items, categories, settings
|
|
- `src/db/index.ts` - Database connection singleton with WAL mode and foreign keys
|
|
- `src/db/seed.ts` - Seeds default Uncategorized category
|
|
- `src/shared/schemas.ts` - Zod validation schemas for items and categories
|
|
- `src/shared/types.ts` - TypeScript types inferred from Zod and Drizzle
|
|
- `src/server/index.ts` - Hono server with health check, static serving, seed on startup
|
|
- `src/client/main.tsx` - React 19 entry with TanStack Router and Query providers
|
|
- `src/client/routes/__root.tsx` - Root layout with Outlet and Tailwind import
|
|
- `src/client/routes/index.tsx` - Default route with placeholder text
|
|
- `src/client/app.css` - Tailwind v4 CSS import
|
|
- `tests/helpers/db.ts` - In-memory SQLite test helper with schema and seed
|
|
|
|
## Decisions Made
|
|
|
|
- Added `routesDirectory` and `generatedRouteTree` config to TanStack Router Vite plugin since routes live in `src/client/routes` instead of the default `src/routes`
|
|
- Installed `better-sqlite3` as a dev dependency because drizzle-kit CLI cannot use Bun's built-in `bun:sqlite` driver
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 3 - Blocking] TanStack Router plugin could not find routes directory**
|
|
- **Found during:** Task 1 (build verification)
|
|
- **Issue:** TanStack Router defaults to `src/routes` but project uses `src/client/routes`
|
|
- **Fix:** Added `routesDirectory: "./src/client/routes"` and `generatedRouteTree: "./src/client/routeTree.gen.ts"` to plugin config
|
|
- **Files modified:** vite.config.ts
|
|
- **Verification:** `bun run build` succeeds
|
|
- **Committed in:** 67ff860 (Task 1 commit)
|
|
|
|
**2. [Rule 3 - Blocking] drizzle-kit push requires better-sqlite3**
|
|
- **Found during:** Task 2 (schema push)
|
|
- **Issue:** drizzle-kit cannot use bun:sqlite, requires either better-sqlite3 or @libsql/client
|
|
- **Fix:** Installed better-sqlite3 and @types/better-sqlite3 as dev dependencies
|
|
- **Files modified:** package.json, bun.lock
|
|
- **Verification:** `bunx drizzle-kit push --force` succeeds
|
|
- **Committed in:** 7412ef1 (Task 2 commit)
|
|
|
|
---
|
|
|
|
**Total deviations:** 2 auto-fixed (2 blocking)
|
|
**Impact on plan:** Both fixes necessary for build and schema tooling. No scope creep.
|
|
|
|
## Issues Encountered
|
|
|
|
None beyond the auto-fixed blocking issues documented above.
|
|
|
|
## User Setup Required
|
|
|
|
None - no external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
|
|
- All infrastructure ready for Plan 01-02 (Backend API: item CRUD, category CRUD, totals, image upload)
|
|
- Database schema in place with tables and foreign keys
|
|
- Shared schemas ready for Hono route validation
|
|
- Test helper ready for service and integration tests
|
|
|
|
---
|
|
*Phase: 01-foundation-and-collection*
|
|
*Completed: 2026-03-14*
|