mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-16 07:39:39 +02:00
a02dceb51c
- ImportModal: 3-tab (URL/Text/AI) import UI with preview before saving - Guide detail: share button → generates 7-day shareable link with copy-to-clipboard - App layout: Import button in sidebar + dynamic ImportModal mount - Library page: Import button in header (desktop), openImportGuide context - Port corrected to 3027 (was 3025, conflict with CityCorners) - CLAUDE.md: full project docs (routes, collections, env vars, phase status) - Root package.json: dev:guides:server, updated dev:guides:app/local/full Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
108 lines
3.9 KiB
Markdown
108 lines
3.9 KiB
Markdown
# Guides — CLAUDE.md
|
|
|
|
Mana Guides is a local-first step-by-step guide app (SOPs, recipes, tutorials, learning paths).
|
|
Port: **5200** (web), **3027** (server)
|
|
Theme: Teal `#0d9488`
|
|
Tier: `beta`
|
|
|
|
## Apps
|
|
|
|
| App | Package | Port | Description |
|
|
|-----|---------|------|-------------|
|
|
| `apps/web` | `@guides/web` | 5200 | SvelteKit 5 local-first UI |
|
|
| `apps/server` | `@guides/server` | 3025 | Hono/Bun compute server (import, share) |
|
|
|
|
## Dev Commands
|
|
|
|
```bash
|
|
pnpm dev:guides:web # Web only
|
|
pnpm dev:guides:server # Server only
|
|
pnpm dev:guides:app # Server + web
|
|
pnpm dev:guides:local # Sync + server + web (no auth)
|
|
pnpm dev:guides:full # Auth + sync + server + web
|
|
```
|
|
|
|
## Architecture
|
|
|
|
**Local-first**: All CRUD goes through `guidesStore` (Dexie.js IndexedDB), synced via mana-sync.
|
|
**Server (port 3025)**: Compute-only — web import via mana-search + mana-llm, shareable links.
|
|
|
|
### Data Model
|
|
|
|
```
|
|
LocalGuide → has many LocalSection, LocalStep
|
|
LocalSection → has many LocalStep (order field)
|
|
LocalStep → belongs to LocalGuide, optional LocalSection
|
|
LocalCollection → has many LocalGuide (ordered list)
|
|
LocalRun → belongs to LocalGuide, stepStates: Record<stepId, StepState>
|
|
```
|
|
|
|
### Collections
|
|
|
|
| Collection | Index | Description |
|
|
|------------|-------|-------------|
|
|
| `guides` | category, difficulty, collectionId | Guide library |
|
|
| `sections` | guideId, order | Optional sections within a guide |
|
|
| `steps` | guideId, sectionId, order | Steps (instruction/warning/tip/checkpoint/code) |
|
|
| `collections` | type | Path or Library groupings |
|
|
| `runs` | guideId, startedAt | Execution history |
|
|
|
|
## Routes
|
|
|
|
```
|
|
/ Library (guide grid, search, filters)
|
|
/guide/[id] Guide detail + edit mode + run history
|
|
/guide/[id]/run Run mode (?mode=scroll|focus)
|
|
/collections Collections grid
|
|
/collections/[id] Collection detail with progress
|
|
/history All run history
|
|
/shared/[token] Public shared guide (no auth needed) — Phase 4
|
|
/(auth)/login Login page
|
|
```
|
|
|
|
## Server Routes (port 3025)
|
|
|
|
```
|
|
POST /api/v1/import/url → fetch URL → mana-search extract → mana-llm → { guide, sections }
|
|
POST /api/v1/import/text → raw text/markdown → mana-llm → { guide, sections }
|
|
POST /api/v1/import/ai → AI prompt → mana-llm → { guide, sections }
|
|
POST /api/v1/share → create shareable link (7-day TTL) → { token, url, expiresAt }
|
|
GET /api/v1/share/:token → retrieve shared guide snapshot
|
|
GET /health → service health check
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
```env
|
|
# Web
|
|
PUBLIC_SYNC_SERVER_URL=ws://localhost:3050
|
|
PUBLIC_GUIDES_SERVER_URL=http://localhost:3027
|
|
|
|
# Server
|
|
PORT=3027
|
|
CORS_ORIGINS=http://localhost:5200
|
|
MANA_SEARCH_URL=http://localhost:3021
|
|
MANA_LLM_URL=http://localhost:3030
|
|
PUBLIC_BASE_URL=http://localhost:5200
|
|
```
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `apps/web/src/lib/data/local-store.ts` | 5 Dexie collections with TypeScript types |
|
|
| `apps/web/src/lib/data/guest-seed.ts` | 3 demo guides, 1 collection for onboarding |
|
|
| `apps/web/src/lib/stores/guides.svelte.ts` | Guide/section/step/collection mutations |
|
|
| `apps/web/src/lib/stores/runs.svelte.ts` | Run start/step state/complete mutations |
|
|
| `apps/web/src/routes/(app)/guide/[id]/run/+page.svelte` | Scroll + focus run modes |
|
|
| `apps/server/src/routes/import.ts` | URL/text/AI import via mana-llm |
|
|
| `apps/server/src/routes/share.ts` | Shareable guide links (in-memory MVP) |
|
|
|
|
## Phase Status
|
|
|
|
| Phase | Status | Description |
|
|
|-------|--------|-------------|
|
|
| 1 | Done | Core CRUD, local-first, guest seed, library/detail/run views |
|
|
| 2 | Done | Collections, StepEditorModal, CollectionEditModal, inline step add |
|
|
| 3 | In progress | Hono server (import + share done), ImportModal frontend, share button |
|
|
| 4 | Planned | DB persistence for shares, /shared/[token] public route, XP/gamification |
|