How tatankam/remap works
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