From 980124be58cf31a7e2d4ea8a667e3dca4c298209 Mon Sep 17 00:00:00 2001
From: Albert <albert@vaporware.studio>
Date: Sat, 16 Aug 2025 23:44:08 +0000
Subject: [PATCH] chore: initialize repo

---
 README.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..27139b1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,83 @@
+# 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.
+
+```d2
+# 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
+```