Skip to content

START_HERE.md

Latest commit

 

History

History
152 lines (122 loc) · 6.08 KB

START_HERE.md

File metadata and controls

152 lines (122 loc) · 6.08 KB
Raw

Start Here: LexiconForge Documentation Index

Welcome to LexiconForge! This document is your map to the codebase.

What is LexiconForge?

LexiconForge is a React-based web application for reading and translating web novels using AI. It supports 8 source sites, multiple AI providers (Gemini, Claude, DeepSeek, OpenAI, OpenRouter), and features like inline illustrations, footnotes, fan translation comparison, and EPUB export.

Live app: lexicon-forge.vercel.app

Quick Start

git clone https://github.com/anantham/LexiconForge.git
cd LexiconForge
npm install
cp .env.example .env.local  # Add your API keys
npm run dev

Documentation by Role

New Contributor

Doc Purpose
ONBOARDING.md Step-by-step guide to your first contribution
../CONTRIBUTING.md Code style, PR process, testing requirements
../AGENTS.md How to work with AI agents on this codebase

Understanding the Architecture

Doc Purpose
ARCHITECTURE.md High-level system design
adr/ Architecture Decision Records (why we built things this way)
Schemas.md Data models for translations, sessions, chapters

Feature-Specific Guides

Feature Doc
Translation pipeline Workers.md
AI providers Providers.md
Image generation ImageGeneration.md
Audio generation Audio.md
EPUB export EPUB.md
Fan translations FanTranslations.md
Settings UI Settings.md

Operations & Debugging

Doc Purpose
EnvVars.md Environment variable reference
DEPLOYMENT.md Deploy to Vercel or self-host
Debugging.md Debug flags and logging
E2E-TESTING.md End-to-end test setup

Roadmaps & Tech Debt

Doc Purpose
CHANGELOG.md Version history and notable changes
TECH-DEBT-STATUS.md Current tech debt items and progress
ARCHITECTURE.md §7 Current hotspots and refactoring watchlist
TypeScript Health Current TS error status

Documentation Structure

docs/
├── START_HERE.md          # You are here
├── ONBOARDING.md          # Newcomer guided tour
├── WORKLOG.md             # Daily work log (multi-agent)
├── Vision.md              # Product vision
│
├── features/              # User-facing feature docs
│   ├── Audio.md, EPUB.md, FanTranslations.md
│   ├── ImageGeneration.md, NOVEL_LIBRARY.md
│   └── COMMUNITY_LIBRARY.md (vision only)
│
├── guides/                # How-to & reference
│   ├── Debugging.md, DEPLOYMENT.md, EnvVars.md
│   ├── META_ADAPTER.md, Providers.md
│   ├── Schemas.md, Settings.md, Workers.md
│   └── (adding new sites, configuring providers, etc.)
│
├── architecture/          # System design
│   └── ARCHITECTURE.md
│
├── adr/                   # Architecture Decision Records
│   ├── DB-001..DB-007     # Database layer
│   ├── CORE-004..CORE-006 # Core architecture
│   ├── FEAT-001..FEAT-002 # Feature design
│   └── SUTTA-003          # Sutta Studio
│
├── infrastructure/        # Testing & tooling
│   ├── E2E-TESTING.md, TEST_MANIFEST.md
│   ├── TYPESCRIPT-HEALTH.md
│   └── CLAUDE-CODE-SCRIPTS.md
│
├── roadmaps/              # Plans & tracking
│   ├── CHANGELOG.md, TECH-DEBT-STATUS.md
│   ├── REMEDIATION-ROADMAP.md
│   └── MEMORY_OPTIMIZATION_ROADMAP.md
│
└── archive/               # Historical docs
    ├── completed/         # Finished plans (IndexedDB, legacy repo)
    ├── stale-docs/        # Outdated (superseded-by headers)
    ├── testing-evolution/  # Test infrastructure journey
    └── diagnostics/       # Old diagnostic artifacts

Architecture Decision Records (ADRs)

ADRs explain why we made key design decisions. They're organized by domain:

Prefix Domain Example
DB- Database/IndexedDB DB-001 - Service decomposition
CORE- Core architecture CORE-005 - Agent-first code organization
FEAT- Feature design FEAT-001 - Preloader strategy, FEAT-003 - Image service
SUTTA- Sutta Studio SUTTA-003 - MVP, SUTTA-004 - Benchmarks, SUTTA-006 - Caching, SUTTA-007 - Pass layer

Key Design Principles

  1. Agent-First: Files stay small and single-purpose (see CONVENTIONS.md §4 for friction-based sizing policy)
  2. Privacy-First: API keys and data stay on-device (IndexedDB)
  3. Provider-Agnostic: Adapters abstract AI providers; easy to add new ones
  4. Offline-Capable: Sessions persist across browser restarts

Getting Help

What's Next?

  1. Read ONBOARDING.md for a guided tour
  2. Pick a good first issue
  3. Check WORKLOG.md to see what's in progress