Book a Demo!
CoCalc Logo Icon
StoreFeaturesDocsShareSupportNewsAboutPoliciesSign UpSign In
sagemathinc
GitHub Repository: sagemathinc/cocalc
 Path: blob/master/src/docs/README.md
10782 views

CoCalc Architecture Documentation for Coding Agents

This directory contains machine-readable architecture documentation for coding agents (Claude Code, Gemini CLI, etc.) working on the CoCalc codebase.

Documents

  • overview.md — High-level system architecture and how components connect

  • frontend.md — Frontend React app: state management, client layer, frame editors

  • conat.md — Conat messaging system: DKV, PubSub, and usage from frontend/project/hub

  • hub.md — Hub server: orchestration, database, project management

  • next.md — Next.js app: API routes, conat bridge, Zod schema validation

  • api.md — External API: Python client, HTTP endpoints, call flow

  • project.md — Project daemon: services, conat integration, file operations

  • syncstrings.md — Syncstrings: real-time collaborative editing, patches, and sync

  • database.md — Database schema: accounts, projects, licenses, purchases, and query system

  • jupyter.md — Jupyter notebooks: kernel management, SyncDB format, execution, ipywidgets

  • frame-editors.md — Frame editors: layout tree, editor specs, registration

  • ai-side-chat.md — Embedded AI side assistant: coding agent, notebook agent, help-me-fix flow, and AI gating

  • frame-editor-dnd.md — Frame editor drag-and-drop: split nodes, tabs, drop zones, tree ops

  • course.md — Course management: students, assignments, handouts, grading

  • project-files.md — File explorer, flyout panel, browsing paths, file actions, drag-and-drop

  • files-terminals.md — File operations, directory listings, terminal sessions

  • auth.md — Authentication: cookies, SSO/OAuth, API keys, registration tokens

  • llm.md — LLM/AI integration: multi-provider routing, cost tracking, streaming

  • latex.md — LaTeX editor: build pipeline, SyncTeX, SageTeX/PythonTeX/Knitr, PDF viewer

Maintenance

IMPORTANT: Feel free to update the documentation. In particular:

  • If you add a new package

  • Notice a difference between code and docs -- code is authoritative

  • Change how conat routing works

  • Modify the API layer

  • Alter the frontend state management patterns

Update the relevant file(s) here. These docs are consumed by coding agents and stale information might cause incorrect code generation.

Last reviewed: 2026-03-11

What is NOT covered

  • compute: The compute server system is not covered in this documentation.