docs: add BUILDANDRUN.md and NEXTSTEP.md developer guides
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.
This commit is contained in:
YetAnotherSuite Dev
parent
2a2b2e5398
commit
93489d5c2b
93
BUILDANDRUN.md
Normal file
93
BUILDANDRUN.md
Normal file
@ -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.
|
||||
143
NEXTSTEP.md
Normal file
143
NEXTSTEP.md
Normal file
@ -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`.
|
||||
Loading…
Reference in New Issue
Block a user