# shao3d/ukido_dyncontinj architecture

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

- Interactive diagram: https://gitdiagram.com/shao3d/ukido_dyncontinj
- Repository: https://github.com/shao3d/ukido_dyncontinj

## Overview

##### Project Type & Purpose
- This is a backend-centric AI chatbot service (no dedicated SPA/web UI)
- Exposes a FastAPI HTTP API (src/main.py)
- Implements a two-stage AI pipeline:
– Stage 1: Gemini router & intent classifier
– Stage 2: Claude response generator
- Uses in-memory/context stores and a markdown-based knowledge base

A. Actor
– “Parent User” (HTTP client)
B. API Layer
– FastAPI Server (src/main.py)
C. AI Processing – Router
– GeminiRouter (src/router.py + src/gemini_cached_client.py)
– Social Detector (src/social_intents.py)
– History Manager (src/history_manager.py)
– Social State Tracker (src/social_state.py)
– Standard Responses (src/standard_responses.py)
– Fuzzy-match logic (patterns in social_intents)
D. Knowledge Base
– Compressed MD docs (data/documents_compressed/*.md)
E. AI Processing – Generator
– ClaudeGenerator (src/response_generator.py + src/openrouter_client.py)
– OpenRouter API (external Claude service)
F. Config & Caches
– src/config.py
– .serena cache & memories (on-disk caches for speed)
G. External Services
– Google AI (Gemini API)
– OpenRouter (Claude API)

##### Architectural Patterns & Principles
- Two-stage pipeline separates classification (Gemini) and generation (Claude)
- Modular design: each core behavior (social, history, routing, generation) lives in its own module
- Configurable context length (HISTORY_LIMIT in config.py)
- Fuzzy matching for social intents to improve UX
- Caching layers (.serena) to reduce repeated LLM calls

##### Technologies & Frameworks
- Python 3.11+
- FastAPI
- Gemini API via gemini_cached_client
- Claude API via openrouter_client
- Markdown docs as Knowledge Base
- pytest + custom scripts under tests/ for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actor
    ParentUser("Parent User"):::actor

    %% API Layer
    FastAPI["FastAPI Server"]:::internal

    %% AI Processing - Router
    subgraph "AI Processing - Router"
        direction TB
        GeminiRouter["GeminiRouter"]:::internal
        SocialDetector["Social Detector"]:::internal
        HistoryManager["History Manager"]:::internal
        SocialStateTracker["Social State Tracker"]:::internal
        StandardResponses["Standard Responses"]:::internal
    end

    %% AI Processing - Generator
    subgraph "AI Processing - Generator"
        direction TB
        ClaudeGenerator["ClaudeGenerator"]:::internal
        SocialResponder["Social Responder"]:::internal
    end

    %% Data Stores
    subgraph "Knowledge Base & Stores"
        direction TB
        KBCompressed[(Compressed MD Docs)]:::datastore
        KBUncompressed[(Uncompressed MD Docs)]:::datastore
        Summaries[(Summaries Store)]:::datastore
        Caches[(.serena Caches)]:::config
        Memories[(.serena Memories)]:::config
    end

    %% Config
    Config["Configuration"]:::config

    %% External Services
    subgraph "External Services"
        direction TB
        GoogleGemini("Gemini API (Google AI)"):::external
        OpenRouterExt("OpenRouter (Claude API)"):::external
    end

    %% Data Flow
    ParentUser -->|POST /chat| FastAPI
    FastAPI -->|invoke router| GeminiRouter
    GeminiRouter -->|classify intent| SocialDetector
    GeminiRouter -->|load history| HistoryManager
    GeminiRouter -->|track state| SocialStateTracker
    SocialDetector -->|fetch docs| KBCompressed
    SocialDetector -->|fetch docs| KBUncompressed
    HistoryManager -->|read/write| Memories
    HistoryManager -->|read| Summaries
    GeminiRouter -->|call API| GoogleGemini
    GeminiRouter -->|hand off| ClaudeGenerator
    ClaudeGenerator -->|generate response| OpenRouterExt
    ClaudeGenerator -->|update context| HistoryManager
    ClaudeGenerator -->|post-process| SocialResponder
    SocialResponder -->|finalize| FastAPI
    FastAPI -->|return JSON| ParentUser

    %% Config Links
    Config --> FastAPI
    Config --> GeminiRouter
    Config --> ClaudeGenerator
    Config --> HistoryManager

    %% Click Events
    click FastAPI "https://github.com/shao3d/ukido_dyncontinj/blob/main/src/main.py"
    click GeminiRouter "https://github.com/shao3d/ukido_dyncontinj/blob/main/src/router.py"
    click GeminiRouter "https://github.com/shao3d/ukido_dyncontinj/blob/main/src/gemini_cached_client.py"
    click SocialDetector "https://github.com/shao3d/ukido_dyncontinj/blob/main/src/social_intents.py"
    click HistoryManager "https://github.com/shao3d/ukido_dyncontinj/blob/main/src/history_manager.py"
    click SocialStateTracker "https://github.com/shao3d/ukido_dyncontinj/blob/main/src/social_state.py"
    click StandardResponses "https://github.com/shao3d/ukido_dyncontinj/blob/main/src/standard_responses.py"
    click SocialResponder "https://github.com/shao3d/ukido_dyncontinj/blob/main/src/social_responder.py"
    click ClaudeGenerator "https://github.com/shao3d/ukido_dyncontinj/blob/main/src/response_generator.py"
    click ClaudeGenerator "https://github.com/shao3d/ukido_dyncontinj/blob/main/src/openrouter_client.py"
    click Config "https://github.com/shao3d/ukido_dyncontinj/blob/main/src/config.py"
    click KBCompressed "https://github.com/shao3d/ukido_dyncontinj/blob/main/data/documents_compressed/*.md"
    click KBUncompressed "https://github.com/shao3d/ukido_dyncontinj/blob/main/data/documents/*.md"
    click Summaries "https://github.com/shao3d/ukido_dyncontinj/blob/main/data/summaries.json"
    click Caches "https://github.com/shao3d/ukido_dyncontinj/tree/main/.serena/cache"
    click Memories "https://github.com/shao3d/ukido_dyncontinj/tree/main/.serena/memories"
    click GoogleGemini "https://github.com/shao3d/ukido_dyncontinj/blob/main/src/gemini_cached_client.py"
    click OpenRouterExt "https://github.com/shao3d/ukido_dyncontinj/blob/main/src/openrouter_client.py"

    %% Styles
    classDef internal fill:#e0f7fa,stroke:#0277bd,stroke-width:1px
    classDef datastore fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px
    classDef config fill:#eeeeee,stroke:#424242,stroke-width:1px
    classDef actor fill:#f3e5f5,stroke:#6a1b9a,stroke-width:1px
```
