# ryu220/kitanoadchecker architecture

> Architecture diagram of the GitHub repository ryu220/kitanoadchecker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ryu220/kitanoadchecker
- Repository: https://github.com/ryu220/kitanoadchecker

## Overview

##### Project type and purpose
- This is a full-stack web application built on Next.js that provides both a React-based UI and a set of RESTful API routes.
- Purpose: automatically check advertising copy against Japanese legal regulations (薬機法, 景表法, etc.) by combining rule-based checks, retrieval-augmented generation (RAG), and LLM/A I.

##### File structure
- app/
- page.tsx, layout.tsx → front-end UI (Next.js App Router)
- app/api/v2/* → API endpoints (segment, evaluate, report, validate-api-key)
- components/ → React UI components (modals, selectors, report display)
- lib/ → core business logic
- segmentation, RAG engine, prompt management, cache manager, validation, vector-db interface
- knowledge/ → raw text files for legal knowledge (common, HA, SH)
- scripts/ → initialization and maintenance scripts (vector DB setup, env checks)
- config/ → static rules and product configurations (keywords, priority mappings)
- docker-compose.yml, Dockerfile → Docker setup for Next.js server and ChromaDB
- docs/ → detailed delivery, deployment, and architecture documentation

##### README for additional insights
- Four-layer “check engine”:
1. NG keyword filtering
2. Annotation-based rules
3. RAG search against vector DB
4. LLM (“Gemini 2.5 Flash Lite”) judgment
- RAG pipeline: chunk knowledge base (~5,129 chunks) → embed → store in ChromaDB → retrieve at runtime
- Two “faces” to the system:
- Web UI (React/Next.js pages)
- API (Next.js serverless functions under app/api/v2)
- Deployment: Docker Compose locally, Railway in production

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client (Browser)" 
        UI["React UI"]:::frontend
    end

    subgraph "Next.js App" 
        direction TB
        subgraph "Presentation Layer"
            Page["page.tsx"]:::frontend
            Layout["layout.tsx"]:::frontend
            ApiKeyModal["ApiKeyModal.tsx"]:::frontend
            ProductSelector["ProductSelectorV2.tsx"]:::frontend
            ProgressTracker["ProgressTrackerV2.tsx"]:::frontend
            ReportDisplay["ReportDisplayV2.tsx"]:::frontend
            AppSpec["AppSpecifications.tsx"]:::frontend
        end
        subgraph "API Layer"
            SegmentAPI["/api/v2/segment"]:::api
            EvaluateAPI["/api/v2/evaluate"]:::api
            EvaluateBatchAPI["/api/v2/evaluate-batch"]:::api
            ReportAPI["/api/v2/report"]:::api
            ValidateKeyAPI["/api/v2/validate-api-key"]:::api
        end
        subgraph "Business Logic Layer"
            SegModule["Segmentation Module"]:::logic
            NGValidator["NG Keyword Validator"]:::logic
            AnnotationAnalyzer["Annotation Analyzer"]:::logic
            RAGEngine["RAG Engine"]:::logic
            PromptManager["Prompt Manager"]:::logic
            CacheManager["Cache Manager"]:::logic
        end
        subgraph "Data Access Layer"
            VectorDBInt["VectorDB Interface"]:::datas
        end
    end

    Chroma["ChromaDB"]:::datas
    Gemini["Google Gemini API"]:::external
    KnowledgeFiles["Knowledge Base Files"]:::datas
    Scripts["Init & Maint Scripts"]:::scripts

    UI -->|"POST JSON"| SegmentAPI
    SegmentAPI -->|"calls"| SegModule
    SegModule -->|LLM request| Gemini
    SegmentAPI --> UI
    UI -->|"POST JSON"| EvaluateAPI
    EvaluateAPI --> NGValidator
    EvaluateAPI --> AnnotationAnalyzer
    EvaluateAPI --> RAGEngine
    RAGEngine --> VectorDBInt
    VectorDBInt --> Chroma
    RAGEngine -->|vector query| Chroma
    RAGEngine -->|retrieved chunks| EvaluateAPI
    EvaluateAPI -->|prompts| PromptManager
    EvaluateAPI -->|cache| CacheManager
    EvaluateAPI -->|LLM call| Gemini
    EvaluateAPI --> ReportAPI
    ReportAPI --> UI
    ValidateKeyAPI --> UI

    KnowledgeFiles -->|loaded by| Scripts
    Scripts --> VectorDBInt

    %% Click Events
    click Page "https://github.com/ryu220/kitanoadchecker/blob/main/app/page.tsx"
    click Layout "https://github.com/ryu220/kitanoadchecker/blob/main/app/layout.tsx"
    click SegmentAPI "https://github.com/ryu220/kitanoadchecker/blob/main/app/api/v2/segment/route.ts"
    click EvaluateAPI "https://github.com/ryu220/kitanoadchecker/blob/main/app/api/v2/evaluate/route.ts"
    click EvaluateBatchAPI "https://github.com/ryu220/kitanoadchecker/blob/main/app/api/v2/evaluate-batch/route.ts"
    click ReportAPI "https://github.com/ryu220/kitanoadchecker/blob/main/app/api/v2/report/route.ts"
    click ValidateKeyAPI "https://github.com/ryu220/kitanoadchecker/blob/main/app/api/v2/validate-api-key/route.ts"
    click ApiKeyModal "https://github.com/ryu220/kitanoadchecker/blob/main/components/ApiKeyModal.tsx"
    click ProductSelector "https://github.com/ryu220/kitanoadchecker/blob/main/components/ProductSelectorV2.tsx"
    click ProgressTracker "https://github.com/ryu220/kitanoadchecker/blob/main/components/ProgressTrackerV2.tsx"
    click ReportDisplay "https://github.com/ryu220/kitanoadchecker/blob/main/components/ReportDisplayV2.tsx"
    click AppSpec "https://github.com/ryu220/kitanoadchecker/blob/main/components/AppSpecifications.tsx"
    click SegModule "https://github.com/ryu220/kitanoadchecker/blob/main/lib/segmentation/index.ts"
    click NGValidator "https://github.com/ryu220/kitanoadchecker/blob/main/lib/ng-keyword-validator.ts"
    click AnnotationAnalyzer "https://github.com/ryu220/kitanoadchecker/blob/main/lib/annotation-analyzer.ts"
    click RAGEngine "https://github.com/ryu220/kitanoadchecker/blob/main/lib/rag-engine.ts"
    click PromptManager "https://github.com/ryu220/kitanoadchecker/blob/main/lib/prompts/evaluation-prompt-command-stack.ts"
    click CacheManager "https://github.com/ryu220/kitanoadchecker/blob/main/lib/cache/prompt-cache-manager.ts"
    click VectorDBInt "https://github.com/ryu220/kitanoadchecker/blob/main/lib/vector-db/chroma-db.ts"
    click KnowledgeFiles "https://github.com/ryu220/kitanoadchecker/tree/main/knowledge/common/"
    click Scripts "https://github.com/ryu220/kitanoadchecker/blob/main/scripts/setup-vector-db.ts"

    classDef frontend fill:#ADD8E6,stroke:#000,color:#000
    classDef api fill:#32CD32,stroke:#000,color:#000
    classDef logic fill:#98FB98,stroke:#000,color:#000
    classDef datas fill:#FFA500,stroke:#000,color:#000
    classDef external fill:#DA70D6,stroke:#000,color:#000
    classDef scripts fill:#D3D3D3,stroke:#000,color:#000
```
