From 785a98ebb0c65cc400d35897fab1460ad3f6959c Mon Sep 17 00:00:00 2001 From: nsfisis Date: Sun, 30 Nov 2025 05:46:10 +0900 Subject: prepare docs --- docs/dev/architecture.md | 256 +++++++++++++++++++++++++++++++++++++++++++++++ docs/dev/roadmap.md | 132 ++++++++++++++++++++++++ 2 files changed, 388 insertions(+) create mode 100644 docs/dev/architecture.md create mode 100644 docs/dev/roadmap.md (limited to 'docs') diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md new file mode 100644 index 0000000..9c3749b --- /dev/null +++ b/docs/dev/architecture.md @@ -0,0 +1,256 @@ +# Kioku Architecture + +## Overview + +Kioku is a spaced repetition learning application (Anki clone) with PWA offline support and cloud sync. + +## Tech Stack + +| Layer | Technology | +|-------|------------| +| Frontend | SvelteKit | +| Backend | Hono + TypeScript | +| Database | PostgreSQL | +| ORM | Drizzle | +| Client DB | Dexie.js (IndexedDB) | +| PWA | @vite-pwa/sveltekit | +| Algorithm | FSRS (ts-fsrs) | +| Auth | username/password + JWT | +| Test | Vitest | +| Monorepo | pnpm workspace | +| Deploy | Docker + VPS | + +## Architecture Diagram + +``` ++--------------------------------------------------+ +| Client (PWA) | +| +-------------+ +------------+ +------------+ | +| | SvelteKit | | Dexie.js | | Service | | +| | UI |<>| (IndexedDB)|<>| Worker | | +| +-------------+ +------------+ +------------+ | +| | | | +| +-------+-------+ | +| | | +| +------v------+ | +| | Sync Engine | | +| +-------------+ | ++--------------------------------------------------+ + | + v HTTPS (REST API) ++--------------------------------------------------+ +| Server | +| +----------------------------------------------+| +| | Hono (TypeScript) || +| | +--------+ +--------+ +--------+ +--------+ || +| | | Auth | | FSRS | | Sync | | Import | || +| | +--------+ +--------+ +--------+ +--------+ || +| +----------------------------------------------+| +| | | +| v | +| +----------------------------------------------+| +| | PostgreSQL (Drizzle) || +| +----------------------------------------------+| ++--------------------------------------------------+ +``` + +## Project Structure + +``` +kioku/ +├── package.json # Workspace root +├── pnpm-workspace.yaml +├── docker-compose.yml +├── apps/ +│ ├── web/ # SvelteKit frontend +│ │ ├── src/ +│ │ │ ├── lib/ +│ │ │ │ ├── components/ +│ │ │ │ ├── stores/ +│ │ │ │ ├── db/ # Dexie IndexedDB +│ │ │ │ ├── sync/ # Sync engine +│ │ │ │ └── api/ +│ │ │ └── routes/ +│ │ └── static/ +│ └── server/ # Hono backend +│ └── src/ +│ ├── routes/ +│ ├── services/ +│ ├── db/ # Drizzle schema +│ ├── middleware/ +│ └── lib/ +│ └── apkg/ # Anki import +└── packages/ + └── shared/ # Shared types + └── src/ + ├── types/ + └── schemas/ # Zod validation +``` + +## Data Models + +### User + +```typescript +interface User { + id: string; // UUID + username: string; // unique + password_hash: string; + created_at: Date; + updated_at: Date; +} +``` + +### Deck + +```typescript +interface Deck { + id: string; + user_id: string; + name: string; + description: string | null; + new_cards_per_day: number; + created_at: Date; + updated_at: Date; + deleted_at: Date | null; // Soft delete + sync_version: number; +} +``` + +### Card (FSRS) + +```typescript +enum CardState { + New = 0, + Learning = 1, + Review = 2, + Relearning = 3, +} + +interface Card { + id: string; + deck_id: string; + front: string; // Plain text + back: string; // Plain text + + // FSRS fields + state: CardState; + due: Date; + stability: number; + difficulty: number; + elapsed_days: number; + scheduled_days: number; + reps: number; + lapses: number; + last_review: Date | null; + + created_at: Date; + updated_at: Date; + deleted_at: Date | null; + sync_version: number; +} +``` + +### ReviewLog + +```typescript +enum Rating { + Again = 1, + Hard = 2, + Good = 3, + Easy = 4, +} + +interface ReviewLog { + id: string; + card_id: string; + user_id: string; + rating: Rating; + state: CardState; + scheduled_days: number; + elapsed_days: number; + reviewed_at: Date; + duration_ms: number | null; + sync_version: number; +} +``` + +## API Design + +### Authentication + +``` +POST /api/auth/register - User registration +POST /api/auth/login - Login (returns JWT) +POST /api/auth/refresh - Refresh token +POST /api/auth/logout - Logout +``` + +### Decks + +``` +GET /api/decks - List decks +POST /api/decks - Create deck +GET /api/decks/:id - Get deck +PUT /api/decks/:id - Update deck +DELETE /api/decks/:id - Delete deck (soft) +``` + +### Cards + +``` +GET /api/decks/:deckId/cards - List cards +POST /api/decks/:deckId/cards - Create card +PUT /api/decks/:deckId/cards/:id - Update card +DELETE /api/decks/:deckId/cards/:id - Delete card +``` + +### Study + +``` +GET /api/decks/:deckId/study - Get cards to study +POST /api/decks/:deckId/study/:cardId - Submit review +``` + +### Sync + +``` +POST /api/sync/push - Push local changes to server +GET /api/sync/pull - Pull server changes +``` + +### Import + +``` +POST /api/import/apkg - Import Anki deck +``` + +## Offline Sync Strategy + +### Approach + +- **Method**: Last-Write-Wins with timestamps +- **Client**: Store in IndexedDB with `_synced` flag +- **Conflict Resolution**: Compare `updated_at`, newer wins +- **ReviewLog**: Append-only (no conflicts) + +### Sync Flow + +1. Local changes saved with `_synced = false` +2. On sync, push pending changes to server +3. Server resolves conflicts by timestamp +4. Client pulls server changes +5. Mark synced items with `_synced = true` + +## Authentication + +- **Hash**: Argon2 for password hashing +- **Access Token**: JWT, 15min expiry +- **Refresh Token**: JWT, 7 days, stored in DB + +## References + +- [ts-fsrs](https://github.com/open-spaced-repetition/ts-fsrs) +- [Anki APKG Format](https://eikowagenknecht.de/posts/understanding-the-anki-apkg-format/) +- [Vite PWA for SvelteKit](https://vite-pwa-org.netlify.app/frameworks/sveltekit.html) +- [Dexie.js](https://dexie.org/) diff --git a/docs/dev/roadmap.md b/docs/dev/roadmap.md new file mode 100644 index 0000000..32af8c7 --- /dev/null +++ b/docs/dev/roadmap.md @@ -0,0 +1,132 @@ +# Kioku Development Roadmap + +## Phase 1: Foundation + +### Project Setup +- [x] Create docs/dev/architecture.md +- [x] Create docs/dev/roadmap.md +- [ ] Initialize pnpm workspace +- [ ] Configure TypeScript +- [ ] Configure Biome +- [ ] Setup Vitest + +### Database +- [ ] Docker Compose with PostgreSQL +- [ ] Drizzle ORM setup +- [ ] Database migrations + +### Shared Package +- [ ] Create packages/shared +- [ ] Define types (User, Deck, Card, ReviewLog) +- [ ] Zod validation schemas + +### Server Foundation +- [ ] Initialize Hono app +- [ ] Error handling middleware +- [ ] Logger middleware + +### Authentication +- [ ] User registration endpoint +- [ ] Login endpoint (JWT) +- [ ] Refresh token endpoint +- [ ] Auth middleware + +## Phase 2: Core Features + +### Server API +- [ ] Deck CRUD endpoints +- [ ] Card CRUD endpoints +- [ ] ts-fsrs integration +- [ ] Study endpoints (get cards, submit review) + +### Frontend Foundation +- [ ] Initialize SvelteKit +- [ ] Setup routing +- [ ] API client + +### Auth UI +- [ ] Login page +- [ ] Register page +- [ ] Auth store + +### Deck Management UI +- [ ] Deck list page +- [ ] Deck detail page +- [ ] Create/edit deck + +### Card Management UI +- [ ] Card list view +- [ ] Create/edit card + +### Study UI +- [ ] Study session page +- [ ] Card flip interaction +- [ ] Rating buttons (Again, Hard, Good, Easy) +- [ ] Progress display + +## Phase 3: Offline Support + +### IndexedDB +- [ ] Dexie.js setup +- [ ] Local schema (with sync flags) +- [ ] Local CRUD operations + +### PWA +- [ ] @vite-pwa/sveltekit configuration +- [ ] Web manifest +- [ ] Service Worker +- [ ] Offline fallback + +### Sync Engine +- [ ] Sync queue management +- [ ] Push implementation +- [ ] Pull implementation +- [ ] Conflict resolution +- [ ] Auto-sync on reconnect + +### Sync API +- [ ] POST /api/sync/push +- [ ] GET /api/sync/pull + +### Sync UI +- [ ] Sync status indicator +- [ ] Manual sync button +- [ ] Offline mode indicator + +## Phase 4: Anki Import + +### Parser +- [ ] ZIP extraction +- [ ] SQLite database reading +- [ ] Note/Card mapping + +### Import API +- [ ] POST /api/import/apkg +- [ ] Progress tracking + +### Import UI +- [ ] File upload +- [ ] Import progress +- [ ] Import results + +## Phase 5: Deployment + +### Docker +- [ ] Dockerfile for server +- [ ] Dockerfile for web (static build) +- [ ] compose.yml (full stack) + +### Production +- [ ] Environment configuration +- [ ] Backup strategy + +### Documentation +- [ ] README.md + +## Future Considerations + +- Statistics and analytics +- Export functionality +- Multiple card types +- Tags and search +- Keyboard shortcuts -- cgit v1.2.3-70-g09d2