# tatankam/remap architecture

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

- Interactive diagram: https://gitdiagram.com/tatankam/remap
- Repository: https://github.com/tatankam/remap

## Overview

##### Project Type and Purpose
- Full-stack event discovery platform (“ReMap”)

##### File Structure
- Top level
– docker-compose.yml: orchestrates backend, frontend, Qdrant containers
– dataset/: example JSON event data
– notebooks/: EDA and proof-of-concept pipelines
– docs/: API + architecture reference, user guide, images/videos
- backend/
– Dockerfile, .dockerignore, requirements.txt
– app/main.py: FastAPI entry point
– app/api/routes.py: HTTP endpoints
– app/core/config.py: environment & service configuration
– app/models/schemas.py: pydantic request/response models
– app/services/:
- openroute_service.py – calls external OpenRouteService API for routing
- qdrant_service.py – interacts with Qdrant for vector + geo + time filtering
- extraction_service.py – generates embeddings (dense & sparse) via crewAI/Mistral
- ingest_service.py & scrape.py – ingestion pipeline for event data
- frontend/
– Dockerfile, .dockerignore, requirements.txt
– streamlit_app.py: UI logic, state, map display using OpenStreetMap
– .streamlit/config.toml: UI theming and secrets

##### Key Architecture Insights from README
- Core technologies: FastAPI, Streamlit, Qdrant, crewAI + Mistral LLM, OpenRouteService, Geopandas/Shapely
- Data flow: user input → route + buffer polygon → hybrid search → event payload → UI
- Containerized deployment for portability

##### Main Components
a. External Actors
– End user (browser/Streamlit client)
– OpenRouteService API (routing)
– CrewAI/Mistral LLM service (embedding extraction)
b. Frontend Layer
– Streamlit app container
c. Backend Layer (FastAPI container)
– API Layer (routes.py)
– Core Config & Validation (config.py + pydantic schemas)
– Service Layer (openroute_service, extraction_service, qdrant_service, ingest_service, scrape)
d. Data Layer
– Qdrant vector database (vector + geo + temporal index)
– Local dataset (JSON files, used by ingestion pipeline)
e. Container Orchestration
– docker-compose: connects frontend, backend, Qdrant

##### Relationships & Interactions
- User → Streamlit UI: HTTP (port 8501)
- Streamlit → FastAPI: REST API calls (via localhost/Docker network)
- FastAPI ↔ OpenRouteService: HTTP requests (routing profiles)
- FastAPI ↔ CrewAI/Mistral: API calls for embedding extraction
- FastAPI ↔ Qdrant:
– Indexing calls (ingest vector + payload)
– Search calls (hybrid semantic + geo + temporal filters)
- Ingestion pipeline (ingest_service + scrape) reads dataset/ → extraction_service → qdrant_service

##### Architectural Patterns & Principles
- Layered architecture (Presentation → API → Services → Data)
- Separation of concerns:
– UI vs business logic vs data persistence
– Vector DB specialized for hybrid search
- Micro-services style (each service class encapsulates a single responsibility)
- Containerization for environment consistency

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    EndUser["End User"]:::user
    StreamlitApp["Streamlit Frontend\n(OpenStreetMap)"]:::frontend
    EndUser -->|UI Interaction| StreamlitApp

    %% Application Layer - Backend
    subgraph "FastAPI Backend" 
        direction TB
        Main["main.py\n(FastAPI Entry)"]:::backend
        subgraph "API Layer"
            Routes["routes.py"]:::api
        end
        subgraph "Core & Models"
            Config["config.py"]:::core
            Schemas["schemas.py"]:::core
        end
        subgraph "Service Layer"
            OpenRoute["OpenRouteService"]:::service
            Extraction["CrewAI/Mistral Embedding"]:::service
            QdrantService["Qdrant Service"]:::service
            Ingest["Ingest Service"]:::service
            Scrape["Scrape Service"]:::service
        end
    end

    StreamlitApp -->|HTTP REST| Routes
    Routes -->|"call routing"| OpenRoute
    Routes -->|"call embedding"| Extraction
    Routes -->|"search & index"| QdrantService

    Ingest --> Extraction
    Ingest --> QdrantService
    Scrape --> Extraction
    Scrape --> QdrantService

    %% External Services
    OpenRoute -->|HTTP REST| ExternalOpenRoute["OpenRouteService API"]:::external
    Extraction -->|HTTP REST| ExternalEmbeddings["CrewAI/Mistral API"]:::external

    %% Data Layer
    QdrantService -->|qdrant-client| QdrantDB[(Qdrant Vector DB)]:::db

    subgraph "Local Dataset"
        direction TB
        DS1["veneto_events_geocoded_structured_example.json"]:::dataset
        DS2["veneto_events_template.json"]:::dataset
        DS3["villages_places.json"]:::dataset
    end
    DS1 --> Ingest
    DS2 --> Ingest
    DS3 --> Ingest

    %% Container Orchestration
    DockerCompose["docker-compose.yml"]:::orchestration
    DockerCompose --> StreamlitApp
    DockerCompose --> Main
    DockerCompose --> QdrantDB

    %% Click Events
    click StreamlitApp "https://github.com/tatankam/remap/blob/main/frontend/streamlit_app.py"
    click Config "https://github.com/tatankam/remap/blob/main/backend/app/core/config.py"
    click Schemas "https://github.com/tatankam/remap/blob/main/backend/app/models/schemas.py"
    click Routes "https://github.com/tatankam/remap/blob/main/backend/app/api/routes.py"
    click OpenRoute "https://github.com/tatankam/remap/blob/main/backend/app/services/openroute_service.py"
    click Extraction "https://github.com/tatankam/remap/blob/main/backend/app/services/extraction_service.py"
    click QdrantService "https://github.com/tatankam/remap/blob/main/backend/app/services/qdrant_service.py"
    click Ingest "https://github.com/tatankam/remap/blob/main/backend/app/services/ingest_service.py"
    click Scrape "https://github.com/tatankam/remap/blob/main/backend/app/services/scrape.py"
    click DS1 "https://github.com/tatankam/remap/blob/main/dataset/veneto_events_geocoded_structured_example.json"
    click DS2 "https://github.com/tatankam/remap/blob/main/dataset/veneto_events_template.json"
    click DS3 "https://github.com/tatankam/remap/blob/main/dataset/villages_places.json"
    click DockerCompose "https://github.com/tatankam/remap/blob/main/docker-compose.yml"

    %% Styles
    classDef user fill:#ffe680,stroke:#333,stroke-width:2px
    classDef frontend fill:#fff2cc,stroke:#333,stroke-width:1px
    classDef backend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef api fill:#b3d7ff,stroke:#333,stroke-width:1px
    classDef core fill:#b3d7ff,stroke:#333,stroke-width:1px
    classDef service fill:#cce0ff,stroke:#333,stroke-width:1px
    classDef external fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef db fill:#d9d9d9,stroke:#333,stroke-width:1px
    classDef dataset fill:#e6e6e6,stroke:#333,stroke-width:1px
    classDef orchestration fill:#f2f2f2,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
