SkyTalk API (api.skytalk.app)

SkyTalk is a backend service designed to power an "AI for Thought" application. It functions as an intelligent, conversational agent that interviews a user to explore and solidify their nascent ideas. The conversation transcript is then synthesized into a structured, semantically-linked knowledge base, styled after the Zettelkasten method.

This MVP is an API-only service, providing the core engine for elicitation, synthesis, and connection, without a frontend interface.

---

Architecture

The system is designed as a monolithic Python application using FastAPI, built for asynchronous performance. It follows a clean, three-layer architecture: API, Services, and Data.

# SkyTalk API Architecture (MVP)
direction: down

# External APIs
ExternalAPIs: {
  shape: cloud
  style.fill: "#DB4437"
  Gemini: "Google Gemini API (2.5 Pro/Flash & Embeddings)"
}

# Main Application Container
SkyTalkAPI: {
  shape: rectangle
  style.fill: "#E3F2FD"
  direction: right

  # API Layer
  API: {
    shape: package
    label: "API Layer (FastAPI)"
    Endpoints: "RPC Endpoints"
    BackgroundTasks: "Background Tasks"
  }

  # Services Layer (Orchestration and Business Logic)
  Services: {
      shape: package
      SessionService: "Session Orchestration"
      InterviewerAgent: "Interviewer Agent (RAG)"
      SynthesizerAgent: "Synthesizer Agent"
      VectorService: "Vector Service"
  }

  # Data Layer
  Data: {
    shape: package
    label: "Data Layer (Async)"
    Repositories: "Session/Note Repositories"
    SQLite: {
      shape: database
      label: "Metadata (SQLite/SQLModel)"
    }
    ChromaDB: {
      shape: database
      label: "Vector Store (ChromaDB)"
    }
  }

  # Connections
  API.Endpoints -> Services.SessionService
  API.BackgroundTasks -> Services.SessionService: "Trigger Synthesis"
  Services.SessionService -> Services.InterviewerAgent
  Services.SessionService -> Services.SynthesizerAgent
  Services.InterviewerAgent -> Services.VectorService: "RAG Retrieval"
  Services.SynthesizerAgent -> Services.VectorService: "Indexing/Neighbors"
  Services.SessionService -> Data.Repositories
  Services.VectorService -> Data.ChromaDB
  Data.Repositories -> Data.SQLite
}

# Connections to External APIs
SkyTalkAPI.Services -> ExternalAPIs.Gemini