Start here
This page is the orientation rail for everyone new to Olly - engineers picking up a service, clinicians shaping a triage pathway, or reviewers checking how the platform hangs together. Work through the four steps below in order; each one points you at the next page to read.
Read the architecture overview
Start with the System Context (L1) to see how Olly sits between members, employers, providers and partner networks. Then drop into the Container Views (L2) for the 14 Go services + triage + frontends, and finish with Business Processes to see how policies, claims, prior auth and triage actually move through the platform.
Next: Run the stack locally so the names on those diagrams point at something running.
Run the stack locally
The whole platform - Postgres, Kafka, Keycloak, APISIX, all 14 Go services, plus triage and the frontends - boots from a single docker-compose. Follow Local Development for the prerequisites, the docker compose up -d recipe, and how to seed demo data so the APIs return something meaningful.
Next: Hit a real endpoint to confirm the stack is live.
Make your first triage call
With the stack up, the fastest sign-of-life is a triage call. Read the triage service page for the public OpenAI-compatible endpoint and an example chat/completions request, then skim the MCP Server page to see the same capabilities surfaced as MCP tools for Claude and other agent runtimes.
Next: Now that you can move requests through the system, learn how access is controlled.
Read the Access Control & Data Protection design doc
Today access control is Keycloak for identity (one olly realm; the JWT's org_locator/party_locator claim scopes each request) with tenancy enforced in application code - not database Row-Level Security. The hybrid authz model (OPA for ABAC policy, Postgres RLS for the floor, OpenBao Transit for at-rest key custody) is a draft design, not yet built - see Data Protection for what's implemented today versus designed. The Access Control & Data Protection design doc walks the target model end-to-end with the invariants, the POC evidence, and the tenant-onboarding flow.
Next: You're oriented. Pick one of the cards below for whatever you're working on first.
The reading order:
1. /architecture/system-context L1 - five actors, seven capabilities
2. /architecture/containers L2 - every Go service, frontend, datastore
3. /architecture/business-processes Dynamic views - claim, enrolment, triage# Quick local preview of the diagram pack:
open https://arch.dev.hiolly.com/# Boot the whole platform - infra + 14 Go services.
cd /root/olly
docker compose up -d
# Wait for everything to be healthy, then seed demo data:
cd infra/local/seeder
python3 -c "import seed; seed.main()"# OpenAI-compatible chat/completions - the canonical public triage endpoint.
curl -sS https://triage.dev.hiolly.com/triage-api/v2/chat/completions \
-H 'Content-Type: application/json' \
-d '{
"model": "olly-triage",
"messages": [
{"role": "user", "content": "I have a sore throat and a fever."}
]
}'Implemented today - identity + app-enforced tenancy:
identity tenancy
| |
Request --> Keycloak (JWT) --> Go service checks org_locator/party_locator
(application-code filter)🚧 Target-state - not yet built (see Designs → Access Control):
identity policy floor at-rest
| | | |
Request --> Keycloak --> OPA --> Postgres RLS --> OpenBao Transit
(JWT) (ABAC) (row filter) (envelope keys)# Confirm your token carries the tenancy claim the services filter on:
curl -sS https://api.dev.hiolly.com/v1/parties/PTY-00001 \
-H "Authorization: Bearer ${OLLY_TOKEN}"