# karthikgs-in/paleolocal architecture

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

- Interactive diagram: https://gitdiagram.com/karthikgs-in/paleolocal
- Repository: https://github.com/karthikgs-in/paleolocal

## Overview

##### Project Type and Purpose
- This is a full-stack, interactive web application (“PaleoLocal”) for discovering and exploring paleogeologic sites.
- Frontend: A React + TypeScript single-page app with a Leaflet map and AI chat UI.
- Backend: A FastAPI service providing search, site metadata, RAG-powered summaries, and chat endpoints.
- Data layer: Local vector store (ChromaDB) and an ingestion pipeline that pulls, chunks, embeds, and stores geological site data.
- External services: Google Gemini LLM (via API), web sources scraped by the ingestion script.

##### File Structure Analysis
- Top-level directories:
- frontend/ – SPA code, React components, hooks, services, config, build tool (Vite).
- backend/ – FastAPI application (main.py, rag_utils.py, prompts.py), scripts for ingestion, requirements.
- data/ – seed_places.csv and auto-generated chunks.jsonl (raw/static data).
- docs/ – usage and interface guides.
- specs/ – feature specs, API contracts, data models, checklists.
- scripts: start-frontend.sh, paleolocal-dev (dev launchers).
- Config files: .env, .gitignore, tsconfigs, package.json, requirements.txt.
- Patterns: clear separation of UI vs API vs data ingestion/embedding. RAG pipeline as a distinct sub-flow.

##### Key README Insights
- Frontend features: interactive map, dynamic side panel, floating/docked chat, responsive UI.
- Backend features: `/api/search`, `/api/place/{id}`, `/api/chat`, RAG retrieval via Chroma + embeddings + Gemini.
- Data ingestion flow: ingest_seed_urls.py → SentenceTransformers → ChromaDB → used at request time.
- Tech stack: React, Leaflet, FastAPI, Uvicorn, ChromaDB, SentenceTransformers, Google Generative AI, Python, Node/Vite.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Browser["Client Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend (React + TypeScript)" 
        direction TB
        MapModule["Map Module"]:::frontend
        SidePanel["Side Panel Module"]:::frontend
        ChatUI["Chat UI Module"]:::frontend
        MockAPI["Mock API (mockAPI.ts)"]:::frontend
        ChatServiceClient["Real Chat Service Client"]:::frontend
    end

    %% Backend Layer
    subgraph "API Layer (FastAPI)" 
        direction TB
        SearchSvc["Search Service (/api/search)"]:::backend
        MetadataSvc["Place Metadata Service (/api/place/{id})"]:::backend
        RAGSvc["RAG Service (retrieval + generation)"]:::backend
        ChatSvc["Chat Service (/api/chat)"]:::backend
        Prompts["Prompt Definitions"]:::backend
        RagUtils["RAG Utils"]:::backend
    end

    %% Data Ingestion Pipeline
    subgraph "Data Ingestion Pipeline" 
        direction TB
        IngestScript["ingest_seed_urls.py"]:::datastore
        WebSources["Web Sources (crawler)"]:::external
        CSV["Seed Data CSV"]:::datastore
        JSONL["Chunked Data JSONL"]:::datastore
        ChromaDB["ChromaDB Vector Store"]:::datastore
    end

    %% External AI Service
    GeminiAPI["Gemini LLM API"]:::external

    %% Flows
    Browser -->|loads SPA| MapModule
    Browser --> SidePanel
    Browser --> ChatUI
    MapModule -->|REST calls| SearchSvc
    SidePanel -->|REST calls| MetadataSvc
    ChatUI -->|/api/chat| ChatSvc
    ChatSvc -->|uses| RAGSvc
    RAGSvc -->|retrieve embeddings| ChromaDB
    RAGSvc -->|use prompts| Prompts
    RAGSvc -->|use utils| RagUtils
    RAGSvc -->|LLM call| GeminiAPI
    SearchSvc -->|reads| CSV
    SearchSvc -->|reads| JSONL

    IngestScript -->|scrapes| WebSources
    IngestScript -->|outputs| JSONL
    IngestScript -->|embeds| ChromaDB

    %% Click Events
    click MapModule "https://github.com/karthikgs-in/paleolocal/tree/main/frontend/src/components/Map/"
    click SidePanel "https://github.com/karthikgs-in/paleolocal/blob/main/frontend/src/components/Map/SidePanel.tsx"
    click ChatUI "https://github.com/karthikgs-in/paleolocal/blob/main/frontend/src/components/Chat/ChatInterface.tsx"
    click MockAPI "https://github.com/karthikgs-in/paleolocal/blob/main/frontend/src/services/mockAPI.ts"
    click ChatServiceClient "https://github.com/karthikgs-in/paleolocal/blob/main/frontend/src/services/chatService.ts"
    click SearchSvc "https://github.com/karthikgs-in/paleolocal/blob/main/backend/app/main.py"
    click MetadataSvc "https://github.com/karthikgs-in/paleolocal/blob/main/backend/app/main.py"
    click ChatSvc "https://github.com/karthikgs-in/paleolocal/blob/main/backend/app/main.py"
    click RAGSvc "https://github.com/karthikgs-in/paleolocal/blob/main/backend/app/rag_utils.py"
    click Prompts "https://github.com/karthikgs-in/paleolocal/blob/main/backend/app/prompts.py"
    click IngestScript "https://github.com/karthikgs-in/paleolocal/blob/main/backend/scripts/ingest_seed_urls.py"
    click CSV "https://github.com/karthikgs-in/paleolocal/blob/main/data/seed_places.csv"
    click JSONL "https://github.com/karthikgs-in/paleolocal/blob/main/data/chunks.jsonl"
    click ChromaDB "https://github.com/karthikgs-in/paleolocal/tree/main/chroma_db/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef backend fill:#E6FFED,stroke:#28A745,color:#28A745;
    classDef datastore fill:#FFF5D1,stroke:#FB8C00,color:#FB8C00;
    classDef external fill:#F0E5FF,stroke:#6F42C1,color:#6F42C1
```
