# cloudkim2025/ai-code-helper architecture

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

- Interactive diagram: https://gitdiagram.com/cloudkim2025/ai-code-helper
- Repository: https://github.com/cloudkim2025/ai-code-helper

## Overview

##### Project type and purpose
- This is a backend‐focused, AI-powered service (“AI 코드 헬퍼”) built with FastAPI. It exposes HTTP REST endpoints and WebSocket channels for real-time chat, and leverages Celery for background tasks (crawling, code analysis). It uses MongoDB to store sessions, crawled documents, logs, and Redis for caching. The system runs in Docker containers orchestrated by Kubernetes.

##### File structure
- Top level: Dockerfile, Kubernetes configs (k8s/), Celery schedules, CI workflow.
- app/ directory:
- db/ – MongoDB connection and CRUD modules
- routes/ – FastAPI routers for crawl, session, part, user_chat_sessions
- schemas/ – Pydantic models for request/response
- services/ – Business logic wrapping OpenAI GPT-4/GPT-3.5 calls
- utils/ – Crawlers, language detection, context detection, Redis caching
- websocket/ – Connection manager and WebSocket endpoint
- celery.py & tasks.py – Celery app and task definitions
- main.py – FastAPI application bootstrap
- k8s/: Deployment and Service YAMLs for API, Celery workers/beat, MongoDB, RabbitMQ, Redis, Ingress.

##### Extract architecture details from the README
- FastAPI handles synchronous HTTP and asynchronous WebSocket traffic.
- MongoDB for persistence, Redis for cache.
- RabbitMQ is the broker for Celery.
- Celery workers perform time-consuming tasks (crawl, analysis).
- Deployed via Docker + Kubernetes.

##### Main components & interactions
a. Components:
- Client (Browser/CLI)
- API Layer (FastAPI server)
- WebSocket Manager
- Celery Broker (RabbitMQ)
- Celery Workers & Beat Scheduler
- GPT Services (external OpenAI API)
- MongoDB (document store)
- Redis (cache)
- Kubernetes Cluster (pods, services, ingress)
b. Relationships & data flows:
1. Client → HTTP request → FastAPI → Routes → Business logic → MongoDB/Redis → Response
2. Client ↔ WebSocket → WebSocket endpoint → ConnectionManager → Session context → Redis/MongoDB → GPT Chat
3. FastAPI task endpoint → Celery.enqueue via RabbitMQ → Celery Worker → GPT Analysis or Crawler → write results to MongoDB → optional Redis cache
4. Celery Beat triggers scheduled crawling tasks → same task flow as above
5. FastAPI may read cached results from Redis for performance
6. All components run in Kubernetes (pods + services) behind an Ingress
c. Architectural patterns & principles:
– Asynchronous messaging (Celery + RabbitMQ) separates web layer from heavy processing
– Layered separation: API vs background workers vs data stores
– Dependency injection & Pydantic schemas for validation
– Real-time bi-directional communication via WebSocket
– Microservice-style isolation of stateful components in separate pods
d. Key technologies: FastAPI, Uvicorn, Celery, RabbitMQ, MongoDB, Redis, Pydantic, Docker, Kubernetes, OpenAI GPT APIs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Client (Browser/CLI)"]:::external
    Client -->|JSON over HTTP| Ingress["Ingress"]:::infra

    %% Kubernetes Ingress and Service
    Ingress --> ServiceAPI["API Service"]:::infra

    subgraph "Kubernetes Cluster"
        direction TB

        subgraph "API Pod"
            direction TB
            FastAPI["FastAPI App"]:::api
            WS["WebSocket Manager"]:::api
            GptChat["GPT Chat Service"]:::api
        end

        subgraph "Celery Beat Pod"
            direction TB
            Beat["Celery Beat Scheduler"]:::bg
        end

        subgraph "Celery Worker Pod"
            direction TB
            Worker["Celery Worker"]:::bg
            GptAnalysis["GPT Analysis Service"]:::bg
        end

        RabbitMQ["RabbitMQ Broker"]:::broker
        Mongo["MongoDB"]:::db
        Redis["Redis Cache"]:::db
    end

    ExternalGPT["OpenAI GPT API"]:::external

    %% Flows
    ServiceAPI --> FastAPI
    FastAPI --> WS
    FastAPI -->|reads/writes| Mongo
    FastAPI -->|cache read/write| Redis
    FastAPI -->|AMQP task message| RabbitMQ
    WS -->|session context| Redis
    WS -->|session persistence| Mongo
    FastAPI -->|invokes| GptChat
    GptChat -->|HTTP request| ExternalGPT

    Beat -->|AMQP schedule| RabbitMQ
    RabbitMQ -->|consume tasks| Worker
    Worker -->|invokes| GptAnalysis
    GptAnalysis -->|HTTP request| ExternalGPT
    Worker -->|writes results| Mongo
    Worker -->|optional cache| Redis

    %% Click Events
    click FastAPI "https://github.com/cloudkim2025/ai-code-helper/blob/main/app/main.py"
    click WS "https://github.com/cloudkim2025/ai-code-helper/blob/main/app/websocket/connection_manager.py"
    click Beat "https://github.com/cloudkim2025/ai-code-helper/blob/main/app/utils/crawler_scheduler.py"
    click Beat "https://github.com/cloudkim2025/ai-code-helper/blob/main/k8s/celery-beat-deployment.yaml"
    click Worker "https://github.com/cloudkim2025/ai-code-helper/blob/main/k8s/celery-deployment.yaml"
    click RabbitMQ "https://github.com/cloudkim2025/ai-code-helper/blob/main/k8s/rabbitmq-deployment.yaml"
    click Mongo "https://github.com/cloudkim2025/ai-code-helper/blob/main/app/db/mongodb.py"
    click Mongo "https://github.com/cloudkim2025/ai-code-helper/blob/main/k8s/mongodb-deployment.yaml"
    click Redis "https://github.com/cloudkim2025/ai-code-helper/blob/main/app/utils/redis_cache.py"
    click Redis "https://github.com/cloudkim2025/ai-code-helper/blob/main/k8s/redis-deployment.yaml"
    click GptChat "https://github.com/cloudkim2025/ai-code-helper/blob/main/app/services/gpt_chat.py"
    click GptAnalysis "https://github.com/cloudkim2025/ai-code-helper/blob/main/app/services/gpt_analysis.py"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#3182CE,color:#1A365D;
    classDef bg fill:#FFDDBA,stroke:#DD6B20,color:#7B341E;
    classDef broker fill:#FED7D7,stroke:#C53030,color:#742A2A;
    classDef db fill:#C6F6D5,stroke:#38A169,color:#22543D;
    classDef infra fill:#E2E8F0,stroke:#A0AEC0,color:#2D3748;
    classDef external fill:#EDF2F7,stroke:#718096,color:#4A5568
```
