# vidyutchakrabarti/kenkomirai architecture

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

- Interactive diagram: https://gitdiagram.com/vidyutchakrabarti/kenkomirai
- Repository: https://github.com/vidyutchakrabarti/kenkomirai

## Overview

##### Project type and purpose
- This is a full-stack, modular simulation platform (“COVID Digital Twin & Containment Simulation”) combining:
- A Next.js frontend for interactive dashboards/maps/charts
- A FastAPI backend hosting the agent-based simulation and chain-of-thought logic
- An ML/RL module (using OpenAI Gym and stable-baselines3) for training disease-containment policies
- Infrastructure (Docker Compose & Kubernetes) to orchestrate services

##### File structure
- Top-level directories:
- assets (static images)
- backend (FastAPI app, API endpoints, simulation code, data ingestion/preprocessing, tests)
- frontend (Next.js app with components, pages, styles)
- infrastructure (docker-compose.yml, k8s manifests, deploy scripts)
- initial datasets (shapefiles, census data)
- ml (training scripts for RL agents)
- Patterns & config files:
- backend/app/api  → REST endpoints
- backend/app/simulation → agent-based model (environment, agent, profiles, RL wrapper)
- backend/app/data → ingest & preprocess raw GIS/census data
- ml/training/train_rl_agent.py → custom Gym environment integration
- infrastructure/docker-compose.yml + k8s/ → multi-service orchestration
- frontend uses Leaflet, Chart.js, Tailwind, Next.js routing

##### README for additional insights
- Confirms a 3-module architecture (Frontend / Backend / ML-RL)
- Highlights external dependencies:
- LLMs for chain-of-thought routines
- OpenAI Gym interface for RL agents (e.g., PPO)
- Visualization libs (Leaflet, Chart.js)
- Describes data flow: agent initialization → simulation → RL policy loop → frontend visualization

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::user

    subgraph "Frontend UI"
        NextJS["Next.js Frontend UI"]:::frontend
        Index["index.tsx"]:::frontend
        Dashboard["dashboard.js"]:::frontend
        SimulationPage["simulation.js"]:::frontend
        Header["Header.tsx"]:::frontend
        MapVis["MapVisualization.tsx"]:::frontend
        SimChart["SimulationChart.tsx"]:::frontend
        UseFetch["useFetch.js"]:::frontend
        Styles["globals.css"]:::frontend
    end

    subgraph "Backend API & Simulation"
        FastAPI["FastAPI Server"]:::backend
        Main["main.py"]:::backend
        Endpoints["endpoints.py"]:::backend
        Models["models.py"]:::backend
        RequirementsBE["requirements.txt"]:::backend
        Utils["logger.py"]:::backend

        subgraph "Simulation Engine"
            Agent["agent.py"]:::simulation
            Profile["agent_profile.py"]:::simulation
            Env["environment.py"]:::simulation
            Routine["daily_routine.py"]:::simulation
            Engine["simulation_engine.py"]:::simulation
            COT["chain_of_thought.py"]:::simulation
            GymEnv["gym_env.py"]:::rl
            RLModule["rl_module.py"]:::rl
        end

        subgraph "Data Layer"
            Ingest["ingest.py"]:::data
            Preprocess["preprocess.py"]:::data
            Config["config.yaml"]:::data
        end
    end

    subgraph "ML/RL Training Module"
        TrainScript["train_rl_agent.py"]:::ml
        MLReq["requirements.txt"]:::ml
        MLDocker["Dockerfile"]:::ml
    end

    InitialData["Initial Datasets"]:::dataStore
    ExternalLLM["LLM Service"]:::external

    subgraph "Infrastructure"
        DockerComp["docker-compose.yml"]:::infra
        K8sDep["deployment.yaml"]:::infra
        K8sSvc["service.yaml"]:::infra
        DeployScript["deploy.sh"]:::infra
    end

    subgraph "Tests"
        TestAPI["test_api.py"]:::test
        TestSim["test_simulation.py"]:::test
    end

    User --> NextJS
    NextJS -->|HTTP calls| FastAPI
    FastAPI -->|loads endpoints| Endpoints
    FastAPI -->|loads models| Models
    FastAPI -->|invokes simulation| Engine
    FastAPI -->|uses logger| Utils

    Engine -->|load shapefiles| Ingest
    Engine -->|load config| Config
    Ingest -->|outputs data| Preprocess
    Engine -->|chain-of-thought prompts| COT
    Engine -->|calls LLM API| ExternalLLM

    GymEnv -->|wraps simulation| Engine
    GymEnv -->|interfaces with| RLModule
    RLModule -->|trains PPO| TrainScript
    TrainScript -->|uses Gym Env| GymEnv

    InitialData --> Ingest
    InitialData --> Preprocess

    DockerComp --> NextJS
    DockerComp --> FastAPI
    DockerComp --> TrainScript
    K8sDep --> NextJS
    K8sDep --> FastAPI
    K8sDep --> TrainScript
    K8sSvc --> NextJS
    K8sSvc --> FastAPI
    DeployScript --> DockerComp
    DeployScript --> K8sDep

    TestAPI --> FastAPI
    TestSim --> Engine

    click Index "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/frontend/src/pages/index.tsx"
    click Dashboard "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/frontend/src/pages/dashboard.js"
    click SimulationPage "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/frontend/src/pages/simulation.js"
    click Header "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/frontend/components/Header.tsx"
    click MapVis "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/frontend/components/Mapvisualization.tsx"
    click SimChart "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/frontend/components/Simulationchart.tsx"
    click UseFetch "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/frontend/src/hooks/useFetch.js"
    click Styles "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/frontend/src/styles/globals.css"

    click Main "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/backend/app/main.py"
    click Endpoints "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/backend/app/api/endpoints.py"
    click Models "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/backend/app/api/models.py"
    click RequirementsBE "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/backend/requirements.txt"

    click Agent "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/backend/app/simulation/agent.py"
    click Profile "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/backend/app/simulation/agent_profile.py"
    click Env "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/backend/app/simulation/environment.py"
    click Routine "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/backend/app/simulation/daily_routine.py"
    click Engine "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/backend/app/simulation/simulation_engine.py"
    click COT "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/backend/app/simulation/chain_of_thought.py"
    click GymEnv "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/backend/app/simulation/gym_env.py"
    click RLModule "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/backend/app/simulation/rl_module.py"

    click Ingest "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/backend/app/data/ingest.py"
    click Preprocess "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/backend/app/data/preprocess.py"
    click Config "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/backend/app/data/config.yaml"

    click TrainScript "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/ml/training/train_rl_agent.py"
    click MLReq "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/ml/requirements.txt"
    click MLDocker "https://github.com/vidyutchakrabarti/kenkomirai/tree/main/ml/Dockerfile"

    click DockerComp "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/infrastructure/docker-compose.yml"
    click K8sDep "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/infrastructure/k8s/deployment.yaml"
    click K8sSvc "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/infrastructure/k8s/service.yaml"
    click DeployScript "https://github.com/vidyutchakrabarti/kenkomirai/blob/main/infrastructure/scripts/deploy.sh"

    classDef user fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef frontend fill:#AEDFF7,stroke:#000,stroke-width:1px
    classDef backend fill:#A0E7E5,stroke:#000,stroke-width:1px
    classDef simulation fill:#B3F7C2,stroke:#000,stroke-width:1px
    classDef rl fill:#9DF7B2,stroke:#000,stroke-width:1px
    classDef data fill:#FFD7A0,stroke:#000,stroke-width:1px
    classDef dataStore fill:#FFBF00,stroke:#000,stroke-width:1px
    classDef ml fill:#DDBDF1,stroke:#000,stroke-width:1px
    classDef infra fill:#F7D6D0,stroke:#000,stroke-width:1px
    classDef external fill:#FFFFFF,stroke-dasharray:5 5,stroke:#000
    classDef test fill:#F0F0F0,stroke:#000,stroke-width:1px
```
