Overview

Relevant source files

• README.md
• app/ClientLayout.tsx
• app/layout.tsx
• docs/translations/README.ar.md
• docs/translations/README.de.md
• docs/translations/README.es.md
• docs/translations/README.fr.md
• docs/translations/README.hin.md
• docs/translations/README.pt-br.md
• docs/translations/README.ru.md
• docs/translations/README.tr.md
• docs/translations/README.vi.md
• docs/translations/README.zh-CN.md
• docs/translations/README.zh-tw.md
• middleware.ts
• next.config.ts
• public/manifest.json
• shared/components/misc/RandomFact.tsx

Purpose and Scope

This document provides a high-level introduction to KanaDojo, a web-based Japanese language learning platform. It covers the application's purpose, architecture, technology stack, and how major systems interconnect. For detailed information about specific subsystems, see the Architecture section (#2) and subsequent chapters.

What is KanaDojo?

KanaDojo is a Next.js 15 web application for learning Japanese language fundamentals. The codebase is organized around three learning domains ("dojos"):

Dojo	Content	File Location	Route
Kana	Hiragana/Katakana syllabaries	features/Kana/data/kana.ts	/[locale]/kana
Kanji	JLPT N5-N2 characters	public/data-kanji/*.json	/[locale]/kanji
Vocabulary	JLPT N5-N2 word sets	public/data-vocab/*.json	/[locale]/vocabulary

The architecture uses:

• Feature-based modules: Self-contained directories under features/ (Kana, Kanji, Vocabulary, Preferences, Progress, Achievements, etc.)
• State management: Zustand stores (useKanaStore, useKanjiStore, useVocabStore, useStatsStore, usePreferencesStore) with localStorage persistence via zustand/middleware
• Theme system: 100+ themes generated from base colors using OKLCH color space transformations in features/Preferences/data/themes.ts and features/Preferences/lib/theme/buildTheme.ts
• UI framework: Tailwind CSS with shadcn/ui components, custom CSS variables for runtime theme switching
• Internationalization: next-intl with middleware-based locale routing in middleware.ts

Sources: README.md37-55 next.config.ts1-164 middleware.ts1-39

High-Level Architecture

The following diagram maps natural language concepts to concrete code entities:

Figure 1: KanaDojo System Architecture with Code References

Key architectural patterns:

1. Server/Client Split: app/layout.tsx is server-rendered (metadata, analytics), app/ClientLayout.tsx is client-rendered (theme application, user interactions)
2. Feature Isolation: Each dojo has its own Zustand store with separate localStorage persistence keys
3. Adaptive Learning: shared/lib/adaptiveSelection.ts provides a singleton GlobalAdaptiveSelector using IndexedDB for weight persistence
4. Theme System: Pure functions in features/Preferences/lib/theme/ transform base themes into full color palettes without component coupling
5. Routing: Next.js 15 App Router with dynamic segments [locale], [type], [mode] for internationalized training routes

Sources: app/layout.tsx1-207 app/ClientLayout.tsx1-151 middleware.ts1-39

Technology Stack

Category	Technologies	Purpose
Core Framework	Next.js 15, React 19, TypeScript 5	Server-side rendering, type safety, app routing
Styling	Tailwind CSS, shadcn/ui, Framer Motion	Utility-first CSS, component library, animations
State Management	Zustand, Zustand Persist	Lightweight state with localStorage persistence
Data Storage	localStorage, IndexedDB	User preferences, adaptive learning weights
Internationalization	next-intl	Multi-language support with 9 namespaces
Audio	use-sound	Sound effect feedback system
Build Tools	ESLint, next-sitemap	Code quality, SEO optimization
Analytics	@vercel/analytics, @vercel/speed-insights	Usage tracking, performance monitoring

Sources: README.md152-193 package.json

Application Structure

The codebase follows a feature-based organization with strict layer separation:

Figure 2: Directory Organization with Import Flow

Layer Import Rules (enforced by ESLint in eslint.config.mjs):

• app/ → can import from features/, shared/, core/
• features/ → can import from shared/, other features/ (via public exports)
• shared/ → cannot import from features/ (prevents circular dependencies)
• core/ → minimal dependencies (infrastructure only)

Feature Module Structure (example: features/Kanji/):

features/Kanji/
├── components/           # UI components (KanjiCards, LevelSetCards)
├── services/            # Data fetching (kanjiDataService.ts)
├── store/               # Zustand store (useKanjiStore.ts)
├── types/               # TypeScript interfaces
└── index.ts             # Public facade (exports only what other features need)

Key Design Decisions:

1. Static data split: Kana data is in features/Kana/data/kana.ts (small, can be bundled), Kanji/Vocab data is in public/ (large JSON files, fetched on demand)
2. Store persistence: Each Zustand store has a unique localStorage key ('kana-storage', 'kanji-storage', etc.)
3. Component library: shadcn/ui components in shared/components/ui/ are generated and customized locally
4. Theme generation: Base themes in features/Preferences/data/themes.ts → buildTheme() generates full themes → applyTheme() sets CSS variables

Sources: README.md347-403 next.config.ts34-42 ESLint configuration inferred from diagrams

Core Systems Overview

Content Organization

Learning content is structured for efficient loading and modularity:

Content Type	File Location	Organization	Loading Strategy
Kana	features/Kana/data/kana.ts	KanaGroup[] grouped by type (Hiragana/Katakana) and category (Base, Dakuon, Yoon, Foreign)	Bundled (5KB, static import)
Kanji	public/data-kanji/N5.json public/data-kanji/N4.json public/data-kanji/N3.json public/data-kanji/N2.json public/data-kanji/decorations.json	JLPT levels, each JSON contains Kanji[] with character, readings, meanings	Lazy loaded via fetch() in features/Kanji/services/kanjiDataService.ts
Vocabulary	public/data-vocab/n5.json public/data-vocab/n4.json public/data-vocab/n3.json public/data-vocab/n2.json	JLPT levels, each JSON contains VocabWord[] with word, readings, meanings, wordTypes	Lazy loaded via fetch() in features/Vocabulary/services/vocabDataService.ts
Facts	public/japan-facts.json	string[] of Japan/Japanese language facts	Lazy loaded in shared/components/misc/RandomFact.tsx with module-level cache
Proverbs	public/japanese-proverbs.json	Proverb[] with Japanese text and English translation	Lazy loaded on demand

Data Service Pattern (Kanji example):

This pattern ensures:

1. No double-fetching: Module-level cache prevents redundant network requests
2. Progressive loading: Only requested levels are loaded
3. Cache retention: Data persists across component remounts

Caching Strategy:

• Kana: No cache needed (bundled with app)
• Kanji/Vocab: In-memory cache in service files (Map-based)
• Random Facts: Module-level factsCache variable with loading promise deduplication in RandomFact.tsx:7-23
• Adaptive weights: IndexedDB via GlobalAdaptiveSelector in shared/lib/adaptiveSelection.ts

For detailed content data structures, see Data Organization (#2.4).

Sources: shared/components/misc/RandomFact.tsx1-64 app/layout.tsx189-192

State Management Flow

Figure 3: State Management Data Flow

State flows through Zustand stores which automatically persist to localStorage via the Zustand Persist middleware. Each feature has its own store (useKanaStore, useKanjiStore, useVocabStore) for managing content selections and game modes. The useStatsStore tracks progress across all content types. The usePreferencesStore manages UI customization settings.

For detailed state management architecture, see State Management (#2.3).

Sources: README.md457-464

Training Flow

The training flow involves component orchestration, routing, and state updates:

Figure 4: Training Session Flow with Code References

Key Components:

1. Content Selection:

   • DojoMenu component renders dojo-specific cards
   • For Kanji: KanjiCards → LevelSetCards (N5, N4, N3, N2)
   • Selection state stored in useKanjiStore() with localStorage key 'kanji-storage'

2. Selection Display:

   • SelectionStatusBar uses getSelectionLabels() utility to format ranges
   • Example: [1, 2, 3, 5, 7, 8, 9] → "1-3, 5, 7-9"

3. Game Mode Selection:

   • GameModes modal persists mode choice to store
   • Modes: 'pick', 'input', 'pick-reverse', 'input-reverse', 'word-building'

4. Routing:

   • Dynamic route: app/[locale]/[type]/train/[mode]/page.tsx
   • Example: /en/kanji/train/pick → renders PickGame with Kanji data

5. Adaptive Question Generation:

   • GlobalAdaptiveSelector singleton in shared/lib/adaptiveSelection.ts
   • Uses IndexedDB database 'adaptive-weights' to persist character weights
   • Higher weight = more likely to appear (increased on wrong answers)

6. Statistics Tracking:

   • useStatsStore() tracks per-session and cumulative stats
   • saveSession() function updates:
     • Correct/wrong counts
     • Answer streaks
     • Character-level mastery (tracked in characterMastery object)
     • Achievement progress

For detailed game mode implementations, see Game System (#4).

Sources: High-level diagram 3, shared/components/misc/RandomFact.tsx1-64 (similar caching pattern)

Theme System Pipeline

The theme system uses mathematical color generation from minimal input:

Figure 5: Theme Generation and Application Pipeline

Theme Generation Mathematics (OKLCH color space):

Generated Color	Light Mode Formula	Dark Mode Formula	Purpose
cardColor	l + 0.05, c * 0.5	l + 0.1, c * 1.2	Elevated surfaces
borderColor	l - 0.1, c * 0.3	l + 0.15, c * 0.8	Subtle dividers
mainAccentColor	l - 0.1, c * 1.2	l - 0.1, c * 1.2	Interactive states (hover)
secondaryAccentColor	l - 0.1, c * 1.2	l - 0.1, c * 1.2	Secondary interactions

Key Functions:

1. buildTheme(baseTheme: BaseTheme, isLight: boolean): Theme:

   • Parses 3 input colors (backgroundColor, mainColor, secondaryColor) using parseOklch()
   • Generates 4 derived colors using mathematical transformations
   • Returns 7-color Theme object

2. applyTheme(themeId: string): void:

   • Finds theme in THEME_GROUPS array by ID
   • Calls buildTheme() with isLight flag from BaseThemeGroup
   • Sets CSS custom properties on document.documentElement
   • Sets data-theme attribute for potential CSS selectors

3. useCrazyMode() (in features/CrazyMode/):

   • Watches usePathname() hook
   • On pathname change, randomly selects theme from THEME_GROUPS
   • Applies via applyTheme()

CSS Variable Integration:

• Tailwind config extends theme with CSS variables
• Components use: className="bg-[var(--card-color)] text-[var(--main-color)]"
• No hardcoded colors in components = instant theme switching

Persistence:

• Theme ID stored in usePreferencesStore() with localStorage key 'preferences-storage'
• applyTheme() called in ClientLayout on mount: useEffect(() => { applyTheme(effectiveTheme); }, [effectiveTheme]);

For 100+ theme definitions and generation details, see Theming System (#3.2).

Sources: app/ClientLayout.tsx83-90 High-level diagram 4

User Journey

A typical user session involves this sequence of components and state changes:

Figure 6: Complete User Journey with State Flow

Key Interactions:

1. Initial Load (app/layout.tsx:132-207):

   • Server-rendered metadata (SEO, social media tags)
   • Analytics conditionally loaded (production only)
   • ClientLayout mounts, reads usePreferencesStore() from localStorage
   • Theme applied via applyTheme() before first paint

2. Navigation (app/ClientLayout.tsx:1-151):

   • Sidebar component provides navigation links
   • Next.js App Router handles client-side routing
   • Scroll position managed by next-scroll-restoration

3. Content Selection:

   • Each dojo page renders its own card component
   • Cards toggle selection in respective Zustand store
   • SelectionStatusBar displays formatted selection summary
   • All state persists to localStorage on change

4. Training Configuration:

   • TrainingActionBar checks if selections exist
   • GameModes modal shows available modes (Pick, Input, Word Building)
   • Mode selection saves to store, triggers route change

5. Game Session:

   • Game component mounts, reads selections from store
   • Loads content via data service (Kanji/Vocab) or static import (Kana)
   • GlobalAdaptiveSelector generates questions based on performance history
   • Each answer updates useStatsStore() in real-time

6. Completion and Review:

   • Return component shows session summary with star rating
   • Stats automatically saved to localStorage
   • useAchievementStore() checks unlock conditions
   • Progress page aggregates data from useStatsStore() for visualization

Sources: app/layout.tsx132-207 app/ClientLayout.tsx56-150 High-level diagrams 3, 6

Development Patterns

Feature Module Pattern

Each feature follows this structure:

features/[FeatureName]/
├── components/          # Feature-specific UI components
├── store/              # Zustand store for feature state
├── data/ or services/  # Static data or data fetching services
├── lib/                # Feature-specific utilities
├── types/              # TypeScript types
└── index.ts            # Barrel export for public API

Features export their public API through index.ts and can import from shared/ or other features when needed. The facade pattern is used in features like Preferences (useThemePreferences, useAudioPreferences) and Progress (useGameStats, useStatsDisplay) to provide controlled access to internal stores.

Sources: README.md449-456 README.md196-208

Routing Pattern

Routes follow the pattern: /[locale]/[feature]/[action]/[param]

Examples:

• /en/kana - Kana dojo main page
• /en/kanji/train/pick - Kanji pick game
• /en/vocabulary/train/word-building - Vocabulary word building game
• /en/preferences - Settings page
• /en/progress - Statistics page

The [locale] segment enables internationalization. For routing details, see Routing and Internationalization (#2.6).

Sources: README.md379-392 README.md477-485

Summary

KanaDojo is a sophisticated Japanese learning platform built on modern web technologies with a focus on architecture quality, user experience, and maintainability. The feature-based organization, comprehensive state management, and flexible theming system provide a solid foundation for continuous enhancement. The following chapters explore each system in detail, explaining implementation specifics, design decisions, and extension points.

Sources: README.md1-655 High-level diagrams provided