How kimyounil1/honey-pot works
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.