Trusty Gateway

Trusty is a multi-tenant RAG gateway built with Go and PostgreSQL. It enforces tenant isolation with PostgreSQL Row-Level Security, retrieves only authorized documents through RBAC-aware vector search, and generates grounded answers using semantic search plus policy checks.

What It Does

Trusty provides the backend for secure, tenant-aware document search and question answering.

Core capabilities:

• Tenant isolation with PostgreSQL Row-Level Security
• JWT authentication with team-based access context
• Document ingestion from URLs
• Text normalization, chunking, embedding, and storage
• Vector search with RBAC filtering
• RAG question answering over authorized content
• Policy checks for access and response grounding
• Local development with Docker, PostgreSQL, embeddings, and optional NLI service

Why It Exists

Standard RAG systems often retrieve from a shared index without strong permission boundaries. Trusty is designed for environments where every answer must respect tenant isolation and document-level access rules.

The main goal is simple: users should only retrieve and generate answers from content they are allowed to see.

Architecture

graph TD
    Client[Client] -->|JWT + Request| API[Go API]
    API --> Auth[Tenant Middleware]
    Auth --> Tx[Transaction Guard]
    Tx --> DB[(PostgreSQL + RLS)]

    API --> Ingest[Ingestion Pipeline]
    Ingest --> Scraper[URL Scraper]
    Ingest --> Chunker[Chunker]
    Chunker --> Embed[Embedding Service]
    Embed --> DB

    API --> Retrieval[Retrieval Service]
    Retrieval --> Embed
    Retrieval --> DB

    API --> Policy[Policy Engine]

Loading

Tech Stack

• Go
• PostgreSQL with Row-Level Security
• pgvector
• Docker Compose
• Python embedding service
• Auth0 JWTs
• Gemini integration
• Optional NLI service for grounding checks

Quick Start

Prerequisites

• Go 1.25+
• Docker Desktop
• Python 3.10+
• Make

Setup

git clone <repo-url>
cd trusty

cd backend
go mod download
cd ..

make up
make migrate-up
make seed
make run

Backend:

http://localhost:8080

Health checks:

curl http://localhost:8080/healthz
curl http://localhost:8080/db/healthz

Fast Local Development

Use this path when you want faster backend iteration without rebuilding the app container.

make down
make db

docker compose up -d embeddings
curl http://localhost:8000/health

make migrate-up
make seed
make run

If the embedding model download is slow, use a smaller model:

EMBED_MODEL="sentence-transformers/all-MiniLM-L6-v2" docker compose up -d embeddings

Frontend

If using the local frontend:

npm --prefix frontend install
npm --prefix frontend run dev -- --port 3000

Frontend:

http://localhost:3000

Common Commands

make up              # Start full local stack
make down            # Stop local stack
make logs            # View service logs
make db              # Start only PostgreSQL
make psql            # Open PostgreSQL shell
make run             # Run backend locally
make dev             # Run backend with live reload
make seed            # Seed local dev data

Database Migrations

make migrate-create name=add_table_name
make migrate-up
make migrate-down
make migrate-version

Migrations live in:

backend/database/migrations/

Configuration

Environment variables are loaded from .env.

Start from:

cp .env.example .env

Important variables:

DATABASE_URL
EMBED_ENDPOINT
NLI_ENDPOINT
GEMINI_API_KEY
JINA_API_KEY
GROUNDING_SEMANTIC_WEIGHT
GROUNDING_NLI_WEIGHT
CHUNK_SEMANTIC_ENABLED

API Overview

Public:

GET /healthz
GET /db/healthz

Protected:

POST /api/v1/documents
GET  /api/v1/documents
GET  /api/v1/documents/{id}

POST /api/v1/search
POST /api/v1/ask

POST /api/v1/policy/evaluate

Project Structure

trusty/
├── backend/
│   ├── cmd/                 # Server and CLI entrypoints
│   ├── internal/            # API, services, storage, infra
│   ├── database/            # Migrations and seed data
│   ├── pkg/                 # Shared packages
│   └── scripts/embeddings/  # Python embedding service
├── frontend/                # Local UI
├── docs/                    # Design notes
├── docker-compose.yml
├── Dockerfile
└── Makefile

Security Model

Trusty uses PostgreSQL Row-Level Security for tenant isolation. Each request sets the active tenant context before database access, and tenant-scoped tables enforce policies at the database layer.

Document access is additionally filtered through RBAC. Users belong to groups, documents define ACLs, and retrieval only returns documents the user is allowed to read.

Troubleshooting

If the app container keeps restarting after backend changes:

docker compose rm -sf app
docker compose build --no-cache app
docker compose up -d --force-recreate app
docker compose logs app --tail 80

To reset local services:

make down
make up
make seed

License

Copyright © 2026 Shrikanth Subramanian. All rights reserved.