Engineering answers you can trace.

Part I / The problem

Synapse addresses a familiar failure in document-based AI: an answer sounds convincing, but the reader cannot tell which passage supports it, whether a table was read correctly, or whether important evidence was missed. The product is a research workspace, not just a prompt box over a vector database.

A user connects a collection of documents, waits for structured ingestion, and asks questions across one or many files. The answer should preserve the relationship between claims, source chunks, pages, and relevant figures. Teams can collaborate over explicitly shared libraries while personal conversations remain separate.

Part II / The system

The system separates a responsive edge product, a GPU execution plane, and durable shared state. Next.js 16 and React 19 provide the interface. OpenNext hosts the application on Cloudflare Workers, where route handlers proxy authenticated requests, manage product state, and connect to object storage and email services.

FastAPI exposes chat, pipeline, agent, and graph services on a dedicated compute host. Ingestion is queue-backed rather than tied to a long browser request. Worker processes perform specialized stages, while the reasoning layer assembles evidence and answers. Supabase Postgres holds the tenant model, job state, conversation records, and pgvector embeddings. Cloudflare R2 holds raw and derived files.

One upload, two persistence layers

A file is stored in R2 and a durable preprocessing job is created in Postgres. Workers claim the job's stages and persist intermediate outputs. This keeps expensive layout, OCR, captioning, and embedding work outside the edge request lifetime. Chat can then retrieve the processed representation without re-parsing the entire collection on every question.

Part II / The system

Flattening a PDF into one text string discards the structure that often carries its meaning. A heading changes the interpretation of a passage; a table encodes relationships; a figure can be the only evidence for a result. Synapse turns source files into a structured intermediate representation before retrieval.

The diagram presents the logical stage order. Extraction and captioning have separate worker paths after layout; their outputs are brought into the representation used for chunking. Individual stage processes let the worker planner balance model-heavy tasks against the host's available VRAM rather than loading every model in every process.

Part III / Execution

The model roster separates document perception from text reasoning. A layout detector locates regions, an OCR system reads text, a vision-language model handles visual content, and retrieval uses a dense encoder with an optional cross-encoder reranker. Reasoning roles can select different model identifiers through configuration.

Part III / Execution

A precise lookup and a comparison across many documents need different retrieval behavior. The planner classifies the request, rewrites it when useful, and decomposes complex questions into sub-queries. Spotlight questions can remain narrow; comparison, aggregation, multi-hop, and multi-entity questions may need broader evidence and follow-up searches.

The runtime fans out retrieval, combines dense and lexical candidates where enabled, expands neighboring chunks, and applies cross-encoder reranking. Retrieved material is distilled into an evidence brief while preserving attribution. A relevance/sufficiency grader and a completeness critic can identify gaps before synthesis. These checks are bounded by the selected reasoning mode.

Depth is a budget, not a promise of quality

The runtime can lower these limits with environment caps. More searches or critic calls consume latency and model budget; they do not guarantee a better answer. The useful question is whether a deeper mode recovers missing evidence on a defined evaluation slice.

Part III / Execution

The synthesizer emits references that the server resolves to real source records. Citation and visual markers connect the narrative to retrieved chunks and visual artifacts; the client renders them as inspectable source chips and figure cards. This makes the evidence path available to the reader instead of hiding it behind a generic filename.

Question
  -> retrieved chunks + document/page identity
  -> distilled evidence brief
  -> answer with [[CITE:n]] and [[VISUAL:id]] markers
  -> resolved source records and visual artifacts
  -> inspectable citation chips and inline figures

Source attribution and correctness are different measurements. A cited passage may be real but irrelevant, or a sentence may overstate what the passage establishes. That is why retrieval relevance, answer correctness, citation quality, and honesty are evaluated separately rather than combined into a single unqualified 'accuracy' number.

Part III / Execution

Agent mode handles requests whose output is not only prose. It plans the task, acquires data through parsing and retrieval, chooses an artifact form, and builds a Vega-Lite or Mermaid specification. Validation and a bounded repair path sit between specification generation and delivery.

Numerical data is bound by code rather than left for the model to invent. The generated specification describes how the data should be presented; it is not permission to fabricate the underlying values. A narrative explains the result, assumptions, and sources after the artifact is produced.

Part III / Execution

The graph pipeline starts with processed library content, extracts entities and relationships, resolves duplicate names, and builds nodes and edges with confidence and source references. The resulting graph is persisted and served to the interface for exploration.

A graph is another representation of the evidence, not an independent source of truth. Entity resolution can merge distinct subjects; extraction can infer a relationship that a passage does not actually state. Retaining the originating chunk allows a user to inspect a graph claim and provides a basis for targeted evaluation of extraction and resolution quality.

Part IV / Platform boundaries

Organizations, members, roles, libraries, conversations, and sharing relationships are modeled explicitly. Personal chats remain private, while shared team conversations can use libraries from participating organizations only through the sharing workflow. Postgres row-level security is part of the data boundary.

Every access path still needs to enforce the caller's permissions: listing files, retrieving chunks, resolving citation previews, downloading artifacts, and accessing graphs. In particular, server-side service-role access must be paired with application authorization; database RLS by itself does not prove a service-role request is correctly scoped.

• Treat library sharing as an explicit grant, not an implicit consequence of joining a conversation.
• Test organization isolation on retrieval and artifact endpoints as well as the UI.
• Retain document and chunk identity when evidence moves between agents.
• Do not publish secret keys or infer security certification from the presence of an RLS policy.

Part V / Evidence and evaluation

The evaluation harness uses DOUBLE-BENCH-oriented methodology with single-hop and multi-hop questions. Its full ingestion path converts sampled page images into PDFs and runs the actual parsing, captioning, chunking, embedding, and clustering pipeline. A cheaper OCR-text path starts at chunking and must be reported as a different ingestion condition.

Retrieval-only runs test whether the expected evidence is found without paying for answer synthesis and judging. Answer runs add dual judges, RAGAS-related measurements, citation checks, honesty/overconfidence, latency, throughput, and spend accounting. Persisted run records support aggregation and resuming work.

Page-level and document-level hits are not interchangeable

Rebuilt text PDFs may not preserve the benchmark's original page indices. A document-level match asks whether a retrieved passage belongs to the correct document. A page-level match asks a stricter question about the expected evidence page. The supplied graph below is explicitly document-level hit@5, not page-level retrieval accuracy.

Part VI / Operating the system

The documented deployment uses Cloudflare for the edge application, R2 for artifacts, Supabase for shared state, and a dedicated GPU host such as an NVIDIA L4 VM. Worker planning responds to the available hardware and queued stages. API-only operation is possible when GPU workers are disabled.

Useful monitoring separates queue delay, stage execution time, model/API failures, retrieval behavior, and answer-generation latency. Model names, prompt versions, dataset identity, and run settings should accompany evaluation reports. Otherwise a score change cannot be attributed to a particular code, data, or model change.

Repository responsibility map

Closing / Engineering judgment

The useful engineering lesson is not that more agents make a better product. It is that each responsibility has an explicit place: perception produces structure, retrieval produces candidate evidence, reasoning identifies gaps, synthesis produces a narrative, and evaluation tests those claims independently.

• Preserve structure before building search: tables and figures are evidence, not decoration.
• Bound autonomous work with runtime limits and observable stages.
• Separate retrieval success, citation correctness, and answer quality.
• Treat graphs and generated artifacts as derived views that still need provenance.
• Report uncertainty, degraded checks, and benchmark scope instead of turning a demo into an unqualified reliability claim.