graph LR
Application
Application -->|"GET /xrpc/{method}"| Query
Application -->|"POST /xrpc/{method}"| Procedure
subgraph HappyView
Query["Query Handler<br/><small>Lua Script (Optional)</small>"]
Procedure["Procedure Handler<br/><small>Lua Script (Optional)</small>"]
Spaces["Spaces<br/><small>Permissioned Data</small>"]
end
Procedure --> DB
Query --> DB
Spaces --> DB
Procedure -->|proxy write| PDS["User PDS"]
DB[("SQLite / PostgreSQL<br/><small>records · lexicons · spaces</small>")]
Jetstream["Jetstream<br/><small>WebSocket</small>"] -->|record events| DB
Relay["Relay<br/><small>listReposByCollection</small>"] -->|repo discovery| Backfill
Backfill["Backfill Worker"] -->|listRecords| PDS
Backfill --> DB
Labeler["Labeler<br/><small>WebSocket (out-of-band)</small>"] -->|label events| DB
Queries go through the query handler to the database (SQLite by default, or Postgres). Writes go through the procedure handler to the user’s PDS, then HappyView indexes the record locally. Real-time record events stream in via Jetstream; historical records are backfilled in-process by discovering repos via the relay’s listReposByCollection and fetching records directly from each PDS. Labelers are external services that emit content labels over a direct WebSocket connection — they operate out-of-band, outside the relay/repo system. Spaces provide permissioned data containers with membership-gated access, per-user repo state tracking (LtHash + signed commits), and cross-service credential-based authentication.
sequenceDiagram
participant C as Client
participant X as xrpc_get()
participant R as LexiconRegistry
participant L as Lua Script
participant D as Database
C->>X: GET /xrpc/{method}?params
X->>R: Lookup (must be Query type)
alt Lua script attached
R->>L: Execute script
L->>D: db.query / db.get / db.raw
D-->>L: Results
L-->>X: Response table
else No script
R->>D: Default SQL query (collection from target_collection)
D-->>X: Results
end
X-->>C: JSON response
sequenceDiagram
participant C as Client
participant A as Claims Extractor
participant X as xrpc_post()
participant R as LexiconRegistry
participant L as Lua Script
participant S as OAuth Session
participant P as User PDS
participant D as Database
C->>A: POST /xrpc/{method} + DPoP auth + X-Client-Key
A->>X: Validated claims
X->>R: Lookup (must be Procedure type)
alt Lua script attached
R->>L: Execute script (Record API)
L->>S: Record:save()
else No script
R->>S: Default create/update (auto-detect from uri field)
end
S->>P: Proxy write (createRecord or putRecord)
P-->>S: PDS response
S->>D: Upsert record locally
S-->>C: Forward PDS response
sequenceDiagram
participant C as Client
participant A as AdminAuth Extractor
participant U as Users Table
participant H as Admin Handler
participant D as Database
C->>A: Request + Bearer token
A->>A: Validate claims (API key or service auth JWT)
A->>U: DID lookup
alt Users table empty
U-->>A: Auto-bootstrap as super user
else User found
U-->>A: Load permissions
end
A->>A: Permission check (403 if missing)
A->>H: Authorized request
H->>D: Database operation
D-->>H: Result
H-->>C: JSON response
sequenceDiagram
participant J as Jetstream WebSocket
participant H as HappyView
participant D as Database
participant R as LexiconRegistry
H->>J: Connect (collection filters from indexed lexicons)
loop Stream events
J->>H: Record commit event
alt create / update
H->>D: UPSERT into records table
else delete
H->>D: DELETE from records table
end
end
J->>H: Lexicon schema event (com.atproto.lexicon.schema)
H->>D: Update tracked network lexicons
H->>R: Update in-memory registry
Note over H,D: Cursor persisted to instance_settings for resume on reconnect
Note over H,J: Reconnects on collection filter changes (lexicon add/remove)
sequenceDiagram
participant A as Admin
participant H as HappyView
participant D as Database
participant Relay as Relay
participant PLC as PLC Directory
participant PDS as User PDS
A->>H: POST /admin/backfill
H->>D: Create backfill_jobs record (status = running)
rect rgb(240, 248, 255)
note over H,Relay: Phase 1: Discovery
H->>Relay: listReposByCollection (paginated)
Relay-->>H: List of DIDs
H->>D: Insert backfill_repos rows
end
rect rgb(240, 255, 240)
note over H,PDS: Phase 2: Pipelined resolve + fetch (concurrent)
par Resolver task
loop Unresolved DIDs
H->>PLC: Resolve DID document
PLC-->>H: PDS endpoint
H->>D: Update backfill_repos.pds_endpoint
end
and Fetcher task
loop Resolved DIDs (as they arrive)
H->>PDS: listRecords (paginated)
PDS-->>H: Records
H->>D: UPSERT each record
end
end
end
H->>D: Mark job completed (or failed)
End-to-end tests use wiremock to mock external services (PLC directory, PDSes) and a real database for full integration coverage. By default tests use SQLite; set TEST_DATABASE_URL to a Postgres connection string to test against Postgres.
