prepare docs

1 files changed, 256 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/)