feat: perf optimisation

project-intelligence/decisions-log.md

@@ -0,0 +1,130 @@
+<!-- Context: project-intelligence/decisions | Priority: medium | Version: 1.0 | Updated: 2026-02-27 -->
+
+# Decisions Log
+
+**Purpose**: Record architecture decisions with context and rationale.
+**Last Updated**: 2026-02-27
+
+## Quick Reference
+- **Update When**: New architecture decisions
+- **Audience**: Developers, architects
+
+---
+
+## ADR-001: Use Prisma with MongoDB
+
+**Date**: 2024
+**Status**: Accepted
+
+**Context**: Need database for caching Komga responses and storing user preferences.
+
+**Decision**: Use Prisma ORM with MongoDB adapter.
+
+**Rationale**:
+- Type-safe queries across the app
+- Schema migration support
+- Works well with MongoDB's flexible schema
+
+**Alternatives Considered**:
+- Mongoose: Less type-safe, manual schema management
+- Raw MongoDB driver: No type safety, verbose
+
+---
+
+## ADR-002: Service Layer Pattern
+
+**Date**: 2024
+**Status**: Accepted
+
+**Context**: API routes need business logic separated from HTTP handling.
+
+**Decision**: Create service classes in `src/lib/services/` (BookService, SeriesService, etc.)
+
+**Rationale**:
+- Separation of concerns
+- Testable business logic
+- Reusable across API routes
+
+**Example**:
+```typescript
+// API route (thin)
+export async function GET(request: NextRequest, { params }) {
+  const book = await BookService.getBook(bookId);
+  return NextResponse.json(book);
+}
+
+// Service (business logic)
+class BookService {
+  static async getBook(bookId: string) { ... }
+}
+```
+
+---
+
+## ADR-003: Custom AppError with Error Codes
+
+**Date**: 2024
+**Status**: Accepted
+
+**Context**: Need consistent error handling across API.
+
+**Decision**: Custom `AppError` class with error codes from `ERROR_CODES` constant.
+
+**Rationale**:
+- Consistent error format: `{ error: { code, name, message } }`
+- Typed error codes for client handling
+- Centralized error messages via `getErrorMessage()`
+
+---
+
+## ADR-004: Radix UI + Tailwind for Components
+
+**Date**: 2024
+**Status**: Accepted
+
+**Context**: Need accessible UI components without fighting a component library.
+
+**Decision**: Use Radix UI primitives with custom Tailwind styling.
+
+**Rationale**:
+- Radix provides accessible primitives
+- Full control over styling via Tailwind
+- Shadcn-like pattern (cva + cn)
+
+---
+
+## ADR-005: Client-Side Request Deduplication
+
+**Date**: 2024
+**Status**: Accepted
+
+**Context**: Multiple components may request same data (e.g., home page with series, books, continue reading).
+
+**Decision**: `RequestDeduplicationService` with React query-like deduplication.
+
+**Rationale**:
+- Reduces Komga API calls
+- Consistent data across components
+- Configurable TTL
+
+---
+
+## ADR-006: PWA with Offline Book Storage
+
+**Date**: 2024
+**Status**: Accepted
+
+**Context**: Users want to read offline, especially on mobile.
+
+**Decision**: Next PWA + Service Worker + IndexedDB for storing book blobs.
+
+**Rationale**:
+- Full offline capability
+- Background sync when online
+- Local storage limits on mobile
+
+---
+
+## Related Files
+- `technical-domain.md` - Tech stack details
+- `business-domain.md` - Business context