# kimyounil1/honey-pot architecture

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

- Interactive diagram: https://gitdiagram.com/kimyounil1/honey-pot
- Repository: https://github.com/kimyounil1/honey-pot

## Overview

##### Project Type and Purpose
- This is a full-stack, AI-powered insurance claim management and chat application.
- Frontend: Next.js (React) single-page app for user interactions (assessments, chats, file uploads, notifications).
- Backend: FastAPI microservice (in API/) handling authentication, CRUD operations, LLM orchestration, OCR, policy sync, refund calculations, scheduling, vector DB retrieval.
- Auxiliary service: paddleocr microservice for document OCR.
- Persistence: Relational database (SQLAlchemy models in API/app/models), plus vector DB for embeddings.
- DevOps: Docker Compose orchestrates frontend, backend, OCR service, database.

##### File Structure
- Top-level:
- API/ : FastAPI code (app/, routers/, schemas/, models/, crud/, services/, config, main).
- next-js/ : Next.js frontend (app/, components/, hooks/, lib/, public/, styles/, middleware).
- paddleocr/ : OCR microservice (paddleocr/app/main.py).
- docker-compose.yaml & docker/ : multi-container Docker definitions.
- Backend layers:
- app/routers: HTTP endpoints (REST).
- app/services: Business logic and integration with LLM gateway, vector DB, OCR, policy sync, scheduler.
- app/crud & app/models & app/schemas: Data access (SQLAlchemy + Pydantic).
- app/auth: JWT security.
- app/rag: Retriever for hybrid search over embeddings.
- Frontend patterns:
- app/api: Next.js API routes (proxy to FastAPI).
- app/<feature>: UI pages & render logic.
- components/ui: Design system.
- lib/sendChatRequest.ts: API client utilities.
- Config/Infra:
- docker-compose.yaml: Service definitions.
- docker/*.Dockerfile: Container builds for FastAPI, Next.js, OCR.
- .env: BASE_URL, DB credentials, API keys.

##### README
- Minimal instructions about .env. We infer architecture from code structure.

a. Main Components
1. User Browser (Next.js SPA)
2. Next.js API Routes (Node.js server)
3. FastAPI Backend
4. Relational DB (e.g., PostgreSQL)
5. Vector DB (e.g., Pinecone, Weaviate)
6. PaddleOCR Service
7. External LLM API (OpenAI, Anthropic)
8. Scheduler/Cron (in services/scheduler)
9. File Storage (Local or S3)
10. Notification Service (push/email)
b. Relationships & Data Flow
- Browser → Next.js API Routes: HTTP(S) requests for UI data and actions.
- Next.js Routes → FastAPI: Proxy HTTP calls (BASE_URL).
- FastAPI → DB: CRUD operations via SQLAlchemy.
- FastAPI → Vector DB: Index/query embeddings in services/vector_db & rag/retriever.
- FastAPI → PaddleOCR: REST call to OCR microservice for document text extraction.
- FastAPI → External LLM: LLM gateway service to generate chat/assessment replies.
- FastAPI Scheduler → triggers periodic tasks (policy_sync, non_benefit_seed, etc.).
- FastAPI → Notification Service: push notifications after events (claims updates).
- File uploads flow: Next.js → FastAPI → store in File Storage → OCR & ingestion.
c. Architectural Patterns & Principles
- Layered architecture in backend (routers → services → crud → models).
- Microservice separation: OCR service decoupled via REST.
- API gateway pattern: Next.js acts as edge server and proxy.
- CQRS-style read/write separation implicit in CRUD vs. search vector DB.
- Dependency injection in FastAPI (deps.py).
- Token-based auth (JWT).
d. Key Technologies & Frameworks
- Frontend: Next.js, React, TypeScript, Tailwind CSS, Radix UI components.
- Backend: FastAPI, SQLAlchemy, Pydantic, Uvicorn, JWT, Python.
- OCR: PaddleOCR Python app.
- Vector DB: (implementation in services/vector_db).
- Docker Compose for orchestration.
- External APIs: OpenAI or similar LLM providers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["User Browser (Next.js UI)"]:::frontend
        APIroutes["Next.js API Routes"]:::frontend
        UI -->|"HTTP(S) requests"| APIroutes
    end
    click UI "https://github.com/kimyounil1/honey-pot/tree/main/next-js/"
    click APIroutes "https://github.com/kimyounil1/honey-pot/tree/main/next-js/app/api/"

    %% Frontend Utilities
    subgraph "Frontend Utilities"
        UIcomp["UI Components"]:::frontend
        Hooks["Frontend Hooks"]:::frontend
        APIclient["API Client Utilities"]:::frontend
        UI --> UIcomp
        UI --> Hooks
        UI --> APIclient
    end
    click UIcomp "https://github.com/kimyounil1/honey-pot/tree/main/next-js/components/ui/"
    click Hooks "https://github.com/kimyounil1/honey-pot/tree/main/next-js/hooks/"
    click APIclient "https://github.com/kimyounil1/honey-pot/blob/main/next-js/lib/sendChatRequst.ts"

    %% Backend Layer
    subgraph "Backend Layer"
        FastAPI["FastAPI Service"]:::backend
        Config["Configuration"]:::backend
        click FastAPI "https://github.com/kimyounil1/honey-pot/blob/main/API/app/main.py"
        click Config "https://github.com/kimyounil1/honey-pot/blob/main/API/app/config.py"

        subgraph "FastAPI Internal"
            Routers["Routers (HTTP Endpoints)"]:::backend
            Services["Services (Business Logic)"]:::backend
            CRUD["CRUD Layer"]:::backend
            Models["ORM Models"]:::backend
            Schemas["Schemas"]:::backend
            Auth["Authentication (JWT)"]:::backend
            RAG["RAG Retriever"]:::backend

            Routers --> Services
            Services --> CRUD
            CRUD --> Models
            Routers --> Auth
            Services --> RAG

            click Routers "https://github.com/kimyounil1/honey-pot/tree/main/API/app/routers/"
            click Services "https://github.com/kimyounil1/honey-pot/tree/main/API/app/services/"
            click CRUD "https://github.com/kimyounil1/honey-pot/tree/main/API/app/crud/"
            click Models "https://github.com/kimyounil1/honey-pot/tree/main/API/app/models/"
            click Schemas "https://github.com/kimyounil1/honey-pot/tree/main/API/app/schemas/"
            click Auth "https://github.com/kimyounil1/honey-pot/tree/main/API/app/auth/"
            click RAG "https://github.com/kimyounil1/honey-pot/blob/main/API/app/rag/retriever.py"
        end

        FastAPI -->|"uses config"| Config
        FastAPI -->|"routes calls"| Routers
    end

    %% Scheduler
    Scheduler["Scheduler (Periodic Tasks)"]:::backend
    click Scheduler "https://github.com/kimyounil1/honey-pot/blob/main/API/app/services/scheduler.py"
    Scheduler --> Services
    FastAPI --> Scheduler

    %% Data Stores
    subgraph "Data Stores"
        Postgres[(Relational DB)]:::datastore
        VectorDB[(Vector DB)]:::datastore
        FileStorage[(File Storage)]:::datastore
    end
    FastAPI -->|"SQL queries"| Postgres
    FastAPI -->|"Embedding requests"| VectorDB
    FastAPI -->|"File store ops"| FileStorage

    %% External Services
    subgraph "External Services"
        OCR["PaddleOCR Service"]:::external
        LLM["External LLM API"]:::external
        Notify["Notification Service"]:::external
    end
    FastAPI -->|"REST OCR request"| OCR
    FastAPI -->|"Chat & assessment calls"| LLM
    FastAPI -->|"Send notifications"| Notify
    click OCR "https://github.com/kimyounil1/honey-pot/blob/main/paddleocr/app/main.py"

    %% DevOps & Infrastructure
    DC["Docker Compose"]:::infra
    FastAPIDocker["FastAPI Dockerfile"]:::infra
    NextDocker["Next.js Dockerfile"]:::infra
    OcrDocker["OCR Dockerfile"]:::infra
    Env["Environment Config (.env)"]:::infra

    DC --> UI
    DC --> APIroutes
    DC --> FastAPI
    DC --> OCR
    DC --> Postgres
    DC --> VectorDB
    DC --> FastAPIDocker
    DC --> NextDocker
    DC --> OcrDocker
    DC --> Env

    click DC "https://github.com/kimyounil1/honey-pot/blob/main/docker-compose.yaml"
    click FastAPIDocker "https://github.com/kimyounil1/honey-pot/blob/main/docker/fastapi.Dockerfile"
    click NextDocker "https://github.com/kimyounil1/honey-pot/blob/main/docker/next.Dockerfile"
    click OcrDocker "https://github.com/kimyounil1/honey-pot/blob/main/docker/paddle.Dockerfile"
    click Env "https://github.com/kimyounil1/honey-pot/blob/main/.env(fake)"

    %% Styling
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#D5F5E3,stroke:#27AE60,color:#27AE60
    classDef datastore fill:#FAD7A0,stroke:#DC7633,color:#DC7633
    classDef external fill:#E8DAEF,stroke:#8E44AD,color:#8E44AD
    classDef infra fill:#F2F3F4,stroke:#A6ACAF,color:#17202A
```
