Technical Reference

services:
  web:
    image: ghcr.io/opsqai/opsqai-web:${OPSQAI_VERSION}
    env_file: .env
    ports: ["8080:8080"]
    depends_on: [postgres, redis, minio]

  worker:
    image: ghcr.io/opsqai/opsqai-worker:${OPSQAI_VERSION}
    env_file: .env
    depends_on: [postgres, redis, minio]

  postgres:
    image: ghcr.io/opsqai/postgres-pgvector:16
    environment:
      POSTGRES_USER: opsqai
      POSTGRES_DB: opsqai
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes: [pgdata:/var/lib/postgresql/data]

  redis:
    image: redis:7-alpine

  minio:
    image: minio/minio:latest
    command: server /data --console-address :9001
    volumes: [objects:/data]

volumes:
  pgdata:
  objects:

• 8080 — opsqai-web HTTP (put behind TLS proxy).
• 5432 — Postgres (do not expose externally).
• 6379 — Redis (internal only).
• 9000 / 9001 — MinIO API / console (internal only).

• pgdata — Postgres. Back this up. Do not delete on upgrade.
• objects — MinIO bucket. Back this up. Migrate to external S3 in production.

export interface AiAdapter {
  chat(messages: Message[], opts: ChatOpts): Promise<ChatResult>;
  stream(messages: Message[], opts: ChatOpts): AsyncIterable<Chunk>;
  embed(texts: string[]): Promise<number[][]>;
}

Ship a new provider by implementing this interface and registering it in src/lib/ai/registry.ts. All rate limiting, retries, and cost accounting are handled by the wrapping layer.

1. Extract — PDF / DOCX / HTML → normalised text.
2. Chunk — recursive splitter, ~800 tokens with 120-token overlap.
3. Embed — batched to the configured adapter (Ollama locally); the model's native vector length is authoritative.
4. Store — document_chunks(embedding vector(N)) where N is the probed embedding dimension, with an HNSW index.
5. Retrieve — <-> cosine, top-k=8, MMR re-rank optional.
6. Generate — pass chunks + question as system context; response cites chunk ids.

• s3 — MinIO, AWS S3, Cloudflare R2, Backblaze B2.
• azure-blob — Azure Storage v2.
• filesystem — POSIX path (single-node only; not recommended for HA).

External integrations use /api/public/* routes with signed webhook secrets. See src/routes/api/public/ for the current surface. Server functions (RPC) are for the app UI and are not part of the stability contract.

• document.ingest
• document.embed
• backup.run — nightly at 03:00 local, configurable.
• license.refresh — every 24h.
• audit.rollup — hourly.

• companies, profiles, user_roles
• documents, document_chunks
• conversations, messages
• tickets, workflows, workflow_runs
• platform_config, audit_log, license

Every table has RLS enabled and explicit GRANTs to authenticated / service_role. See migrations for exact policies.