Skip to content
InsightSpaceInsightSpace

Architecture

The diagram below shows the single-appliance on-premises topology currently maintained with the InsightSpace application. All application, data, extraction, and local inference services run on one host, while Caddy is the public entry point.

InsightSpace single-appliance architecture showing users, Caddy, the frontend, backend, PostgreSQL, Garage object storage, the extractor, Ollama, backups, and internal and external networks.

Request path

Section titled “Request path”
  1. A browser connects to the reverse proxy over HTTP or HTTPS.
  2. The proxy routes application traffic to the frontend and API traffic to the backend.
  3. The backend authorizes the user and workspace for each operation.
  4. Relational records and vector embeddings are stored in PostgreSQL with pgvector.
  5. Uploaded files and extraction artifacts are stored in S3-compatible object storage.
  6. The backend submits extraction work to the standalone extractor and receives structured chunks.
  7. Configured model providers supply chat, embedding, and reranking capabilities.

Network boundaries

Section titled “Network boundaries”

The Compose topology separates an external web network from a private internal network.

  • The frontend is reachable through the web tier.
  • The backend connects the web tier to private application services.
  • PostgreSQL, object storage, and the extractor remain on the internal network.
  • Ollama can use a separate egress-capable network when it must retrieve model artifacts.

Only the reverse proxy should expose public ports in a production single-host deployment. Configure trusted proxies so forwarded client addresses used for rate limiting and audit data are accepted only from known infrastructure.

Data boundaries

Section titled “Data boundaries”

The backend owns tenant authorization and orchestration. The extractor is stateless: it holds no database, tenant state, or model-provider credentials. It processes one job in disposable scratch storage and returns structured content to the backend.

For large extraction results, the backend can issue job-scoped S3 upload URLs restricted to an exact result prefix. The extractor does not receive general S3 credentials.

Persistence

Section titled “Persistence”

Persistent data includes:

  • PostgreSQL data and vector embeddings;
  • S3 objects for source files and extraction artifacts;
  • backend data-protection keys; and
  • database backups.

Extractor scratch space is temporary and should be mounted as tmpfs in the hardened container posture. Container images and the extractor root filesystem are intended to be immutable.