prepare docs

2 files changed, 388 insertions, 0 deletions

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