Skip to main content

Architecture Overview

Village Data is built as a modern, serverless-first application with clear separation between frontend, backend, and data layers.

System Architecture​

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Next.js UI    │────▶│   API Server    │────▶│    Supabase     │
│    (Vercel)     │     │ (Digital Ocean) │     │   (Postgres)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │
         │              ┌────────┴────────┐
         │              ▼                 ▼
         │      ┌─────────────┐   ┌─────────────┐
         └─────▶│ MCP Server  │   │   OpenAI    │
                │(Digital Ocean│   │  Google AI  │
                └─────────────┘   └─────────────┘

Components​

Frontend (Next.js)​

  • Framework: Next.js 14 with App Router
  • UI Library: Mantine components
  • Hosting: Vercel
  • Features:
    • Server-side rendering
    • API routes for backend logic
    • Real-time updates via Supabase subscriptions

API Server​

  • Runtime: Node.js
  • Hosting: Digital Ocean App Platform
  • Purpose:
    • Complex backend operations
    • LLM orchestration
    • Background jobs

MCP Server​

  • Framework: FastMCP
  • Protocol: Model Context Protocol
  • Purpose:
    • Dataset querying for AI tools
    • Standardized AI tool interface
    • RAG retrieval

Database (Supabase)​

  • Database: PostgreSQL with pgvector
  • Auth: Supabase Auth (Google OAuth)
  • Storage: Supabase Storage for files
  • Features:
    • Row Level Security (RLS)
    • Real-time subscriptions
    • Edge functions

Data Flow​

User Authentication​

User → Google OAuth → Supabase Auth → JWT → App

Dataset Creation​

User uploads file → API validates → Storage saves → DB records metadata

Chatbot Query (RAG)​

User message → Embed query → Search vectors → Retrieve chunks → LLM generates response

Security Model​

  • Authentication: Supabase Auth with JWT tokens
  • Authorization: Row Level Security policies
  • API Keys: Server-side only, never exposed to client
  • File Access: Signed URLs with expiration