How cokice/japanese-analyzer works
Purpose and runtime
A Next.js 15 / React 19 application for Chinese learners to analyze Japanese sentences: token-level readings and grammar, Chinese translations, word explanations, OCR, TTS, and contextual AI chat. The primary browser entry is app/page.tsx; global shell/theme styling begins at app/layout.tsx and app/globals.css. It runs as a Node/Next server locally, in Docker, or on Vercel.
Client composition and interaction state
The page composes input, analysis output, translation, word-detail, and chat experiences from app/components/InputSection.tsx, app/components/AnalysisResult.tsx, app/components/TranslationSection.tsx, and app/components/AIChat.tsx. app/components/SettingsModal.tsx holds provider/model and user API-key choices in browser-local state; the server retains default keys. Clicked tokens drive the word-detail flow through app/hooks/useWordDetail.ts and app/components/WordDetailPanel.tsx.
Analysis pipeline
Sentence submission uses the client API layer at app/services/api.ts to invoke app/api/analyze/route.ts. The route is the central AI-backed analysis boundary: it selects a configured text provider/model, calls it through shared proxy/config mechanisms, and returns structured sentence analysis for rendering. Client-side Japanese segmentation and presentation transformations are supported by app/utils/japaneseChunking.ts and app/utils/markdown.ts.
Provider abstraction and AI service boundary
Provider resolution, default server credentials, user-supplied credentials, model choice, and endpoint URLs are centralized in app/api/_utils/providerConfig.ts; OpenAI-compatible upstream requests are brokered by app/api/_utils/openaiProxy.ts. Available model definitions are surfaced to the UI through app/lib/aiModels.ts. Text functions—including analysis, translation, word detail, reasoning summaries, and chat—are separate route boundaries at app/api/analyze/route.ts, app/api/translate/route.ts, and app/api/chat/route.ts, with Gemini and DeepSeek as external services.
Multimodal and speech stages
Image-to-text is isolated at app/api/image-to-text/route.ts and is Gemini-only. Speech generation is isolated at app/api/tts/route.ts, supporting Edge TTS by default and Gemini TTS when configured. Reasoning stream/summarization UI state is handled in app/components/ReasoningStream.tsx and app/utils/reasoningSummary.ts, backed by app/api/reasoning-summary/route.ts.
Access control and analytics
Optional password gating is implemented via app/api/auth/route.ts and server-side session checks in app/api/_utils/sessionAuth.ts, using the CODE environment variable. Optional Umami analytics is loaded through a local proxy endpoint at app/api/umami/script/route.ts; client event emission is in app/utils/analytics.ts. The design avoids sending input content or API keys in analytics events.
Deployment and infrastructure
Server defaults come from environment variables for DeepSeek, Gemini, optional access code, and Umami. Container deployment is defined by Dockerfile, docker-compose.yml, and docker-compose.hub.yml; Docker Hub CI is in .github/workflows/docker.yml. vercel.json supports Vercel deployment. External runtime dependencies are DeepSeek’s OpenAI-compatible API, Gemini’s OpenAI-compatible API, Edge TTS, and optionally a hosted Umami instance.
Main entry points: page.tsx Learning workspace · api.ts Client API layer · providerConfig.ts Provider configuration · route.ts OCR and TTS
Components 22
Browser client
- App shell and theme
app/layout.tsx - Learning workspace · Primary sentence-learning entry point.
app/page.tsx - Sentence input
app/components/InputSection.tsx - Analysis and translation
app/components/AnalysisResult.tsx - Contextual chat
app/components/AIChat.tsx - Provider settings · Stores model and user API-key choices locally.
app/components/SettingsModal.tsx - Word detail flow · Clicked tokens open word explanations.
app/hooks/useWordDetail.ts - Client API layer
app/services/api.ts - Reasoning stream
app/components/ReasoningStream.tsx - Privacy-safe analytics · Excludes input content and API keys.
app/utils/analytics.ts
Next.js API
- Sentence analysis · Central structured AI analysis boundary.
app/api/analyze/route.ts - Translation and chat · Separate text-function route boundaries.
app/api/translate/route.ts - Provider configuration · Resolves credentials, models, and upstream endpoints.
app/api/_utils/providerConfig.ts - OpenAI-compatible proxy
app/api/_utils/openaiProxy.ts - OCR and TTS · Gemini OCR; Edge or Gemini speech generation.
app/api/image-to-text/route.ts - Optional access gate · Checks CODE-backed server sessions.
app/api/auth/route.ts - Umami script proxy
app/api/umami/script/route.ts
AI providers
- DeepSeek and Gemini · OpenAI-compatible text services; Gemini also provides OCR and optional TTS.
- Edge TTS
Deployment
- Next.js runtime · Runs locally, in Docker, or on Vercel.
Dockerfile - Docker Hub CI
.github/workflows/docker.yml - Vercel deployment
vercel.json
Connections 21
- App shell and theme → Learning workspace: hosts
- Learning workspace → Sentence input: composes
- Learning workspace → Analysis and translation: renders
- Learning workspace → Contextual chat: composes
- Learning workspace → Provider settings: configures
- Analysis and translation → Word detail flow: token clicks
- Sentence input → Client API layer: submits
- Client API layer → Sentence analysis: analysis request
- Client API layer → Translation and chat: translation and chat
- Contextual chat → Reasoning stream: shows reasoning
- Provider settings → Client API layer: supplies choices
- Sentence analysis → Provider configuration: selects provider
- Translation and chat → Provider configuration: selects provider
- Provider configuration → OpenAI-compatible proxy: configures
- OpenAI-compatible proxy → DeepSeek and Gemini: brokers requests
- OCR and TTS → DeepSeek and Gemini: Gemini OCR/TTS
- OCR and TTS → Edge TTS: default speech
- Optional access gate → Learning workspace: permits access
- Privacy-safe analytics → Umami script proxy: loads and emits
- Next.js runtime → Docker Hub CI: built and published
- Vercel deployment → Next.js runtime: deploys