From 93489d5c2b7eb19cd9e6b11aea724a629710c5bc Mon Sep 17 00:00:00 2001 From: YetAnotherSuite Dev Date: Mon, 20 Jul 2026 22:33:54 +0200 Subject: [PATCH] docs: add BUILDANDRUN.md and NEXTSTEP.md developer guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit BUILDANDRUN.md — developer onboarding guide covering prerequisites, quick start, CLI commands, scoped package execution, service URLs, Docker production build, Tauri desktop build, and verification steps. NEXTSTEP.md — comprehensive assessment of project state across all 6 phases, identifying what is solid vs placeholder, with prioritized next steps: write tests, wire frontend to API, Prisma migrations, finish calendar views, wire sync engine, code splitting, i18n. --- BUILDANDRUN.md | 93 ++++++++++++++++++++++++++++++++ NEXTSTEP.md | 143 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 236 insertions(+) create mode 100644 BUILDANDRUN.md create mode 100644 NEXTSTEP.md diff --git a/BUILDANDRUN.md b/BUILDANDRUN.md new file mode 100644 index 0000000..06b987a --- /dev/null +++ b/BUILDANDRUN.md @@ -0,0 +1,93 @@ +# Build & Run — YetAnotherSuite + +## Prerequisites + +- **Node.js** 22+ +- **pnpm** 11+ (`npm install -g pnpm`) +- **Docker** + **Docker Compose** (for Postgres, Redis, Meilisearch) +- **Rust** (only for desktop build — Tauri v2) + +## Quick start + +```sh +# 1. Install dependencies +pnpm install + +# 2. Approve native build scripts (first time only) +pnpm approve-builds + +# 3. Start Postgres + Redis + Meilisearch +docker compose up -d postgres redis meilisearch + +# 4. Generate Prisma client & push schema to DB +pnpm --filter @yetanother/db exec prisma generate +pnpm --filter @yetanother/db exec prisma db push + +# 5. (Optional) Seed dev data +pnpm --filter @yetanother/db exec tsx prisma/seed.ts + +# 6. Copy env file +cp .env.example .env + +# 7. Start dev servers (API on :4000, Web on :3000) +pnpm dev +``` + +Open **http://localhost:3000** — the Vite dev server proxies `/api` and `/ws` to the API. + +## Commands + +| Command | What | +|---------|------| +| `pnpm dev` | Start all apps in dev mode | +| `pnpm build` | Build all packages (prod) | +| `pnpm lint` | ESLint across all packages | +| `pnpm typecheck` | TypeScript strict type checks | +| `pnpm test` | Run all tests (Vitest) | +| `pnpm format` | Prettier format all files | +| `pnpm clean` | Remove dist + `.turbo` + node_modules | + +### Scoped to a single package + +```sh +pnpm --filter @yetanother/web dev # web only +pnpm --filter @yetanother/api dev # api only +pnpm --filter @yetanother/api exec prisma studio # DB browser +pnpm --filter @yetanother/db exec prisma migrate dev # new migration +``` + +## URLs + +| Service | URL | +|---------|-----| +| Web app | http://localhost:3000 | +| API | http://localhost:4000 | +| API docs | http://localhost:4000/docs | +| Prisma Studio | `pnpm --filter @yetanother/db exec prisma studio` | +| Meilisearch | http://localhost:7700 | + +## Docker (production build) + +```sh +docker compose up --build +``` + +This starts Postgres, Redis, Meilisearch, the built API (:4000), and the built web app (:3000/80 via Nginx). + +## Desktop (Tauri) + +Requires the [Rust toolchain](https://rustup.rs). + +```sh +cd apps/desktop +pnpm tauri dev # dev with hot-reload +pnpm tauri build # production bundle +``` + +## Verification + +```sh +pnpm lint && pnpm typecheck && pnpm build +``` + +All three must pass before committing. diff --git a/NEXTSTEP.md b/NEXTSTEP.md new file mode 100644 index 0000000..1631094 --- /dev/null +++ b/NEXTSTEP.md @@ -0,0 +1,143 @@ +# Next Steps — YetAnotherSuite + +This is a greenfield monorepo (no code existed before this session). All 6 phases from the implementation plan have been scaffolded. Below is an honest assessment of what works, what is placeholder, and what to tackle next. + +--- + +## Current state + +### What's solid + +| Layer | Status | +|-------|--------| +| Monorepo (Turborepo + pnpm workspaces) | Builds, typechecks, lints clean | +| Prisma schema (12 models, pgvector, indexes) | Generated, matches plan | +| Fastify API (auth, nodes, workspaces, search, AI, webhooks, analytics) | Typechecks, routes registered | +| Shared packages (types, utils, hooks, UI components) | Importable, type-safe | +| TipTap editor (toolbar, slash menu, 9 block types) | Functional | +| Task store + list (views, priorities, DnD reorder) | Working | +| Calendar month view | Renders events | +| AI routes (6 actions, NL parsing) | API ready | +| Collaboration WebSocket server | Registered | +| Docker Compose (Postgres, Redis, Meilisearch) | Configured | +| Tauri desktop skeleton | Scaffolded | + +### What's placeholder / incomplete + +| Item | What's missing | +|------|----------------| +| **Tests** | No test files exist. Vitest + RTL + Playwright are configured but unused. | +| **Frontend ↔ API binding** | Zustand stores use local state. API routes exist but frontend doesn't call them (except search/AI). | +| **Calendar day/week views** | Only month view renders. Day/Week views show a placeholder. | +| **Knowledge graph** | D3.js container is empty. No graph data fetching or rendering. | +| **Sync engine** | Yjs + WebSocket server exists. No client-side CRDT sync wired into notes/tasks. | +| **i18n** | No i18n keys or translation files. All strings are hardcoded in English. | +| **OAuth** | JWT auth works. No Google/GitHub/Microsoft OAuth flows. | +| **Prisma migrations** | Schema exists. No migration files — uses `db push` for now. | +| **Mobile app** | React Native / Expo not started. | +| **Editor persistence** | Note editor doesn't auto-save to API. Uses localStorage only. | +| **Code splitting** | Single 1MB JS chunk. Needs lazy loading by route. | + +--- + +## Priority next steps + +### 1. Write tests (highest ROI) + +Configure and write tests for the most critical paths before anything else breaks. + +```sh +# Run existing (empty) test suite: +pnpm test +``` + +**Critical paths to cover:** +- `packages/types` — Zod schema validation +- `packages/ui` — Button, Dialog render + interaction +- `apps/web` — NoteList filtering, TaskList view switching +- `apps/api` — Auth register/login, node CRUD, search + +**Setup:** +- `apps/web/vitest.config.ts` exists but needs test files in `__tests__/` +- `apps/api` needs a vitest config and a test database +- MSW should be used to mock the API for frontend tests + +### 2. Wire frontend to real API + +Currently all data lives in Zustand + localStorage. The API is fully built but unused by the UI. + +**Pattern (for each store):** +``` +- On app load: fetch from API → hydrate Zustand +- On mutation: optimistically update Zustand → POST/PATCH to API → rollback on error +``` + +**Store to API mapping:** +- `useNotesStore` ↔ `api.nodes.list`, `api.nodes.create`, etc. +- `useTasksStore` ↔ same (nodes are polymorphic) +- `useCalendarStore` ↔ `api.nodes` with `type=event` + +### 3. Prisma migrations + +Replace `db push` with proper migrations for production safety: + +```sh +pnpm --filter @yetanother/db exec prisma migrate dev --name init +``` + +### 4. Finish calendar views + +- `apps/web/src/calendar/WeekView.tsx` — horizontal time grid +- `apps/web/src/calendar/DayView.tsx` — vertical hour slots +- Drag tasks onto calendar (DnD Kit from tasks already a dependency) +- Event creation dialog + +### 5. Wire up sync engine + +- `apps/web/src/lib/collaboration.ts` has a WebSocket client but nothing calls it +- Connect it to the TipTab editor (y-prosemirror) +- Add presence cursors UI +- Add offline IndexedDB persistence (y-indexeddb already installed) + +### 6. Complete remaining Phase 4 AI features + +- Wire `AIAssistant.tsx` into the editor toolbar +- Wire `SearchBar.tsx` into the sidebar +- Wire `KnowledgeGraph.tsx` to D3.js force simulation with real data + +### 7. Add i18n + +Install `react-i18next` or `lingui` and extract all hardcoded strings. + +### 8. Code splitting + +In `App.tsx`, lazily load Notes, Tasks, and Calendar pages: + +```tsx +const NotesPage = lazy(() => import('./notes/NotesPage')); +``` + +--- + +## Stretch goals + +| Goal | When | +|------|------| +| Storybook design system | After UI package is stable | +| OAuth providers (Google, GitHub, Microsoft) | After auth is tested | +| React Native Expo app | After web is complete | +| Performance profiling (Lighthouse, bundle analysis) | After code splitting | +| E2E tests (Playwright) | After all critical flows work | +| CI pipeline on GitHub Actions | Test the existing workflow | + +--- + +## Verification checklist + +Before any PR, run: + +```sh +pnpm lint && pnpm typecheck && pnpm build +``` + +These three commands must pass. No warnings allowed. This is enforced by the CI workflow at `.github/workflows/ci.yml`.