TOJI TOJI
ARCHITECTURE · goquest

goquest architecture

goquest is the ticket and work-management service for the whole neunexus ecosystem — agent-first by design, with AI agents rather than humans as its primary user, and a stateless MCP proxy layered on top of its REST API. Every code, infra, and documentation task across the ecosystem is tracked as a ticket (epic/task/sub-task) here, backed by ticket CRUD and a state machine, fine-grained SpiceDB authorization, automatic GitHub linking, and Redis-event-driven follow-up work.

Project overview →

Why

Juggling many different kinds of work meant that when an issue interrupted one task, picking it back up later was hard. Handing off in-progress work from one session to another also carried a steep learning cost. goquest exists to solve both problems — tracking work status and cutting that hand-off cost — with a ticket service. Existing ticket services were often incompatible with our own IAM services, and calling them via API frequently hit missing or broken endpoints, so a new project was built instead.

00

What this project is, and why it exists

overview.json → diagram_spec

goquest is an agent-first ticket system for the neunexus ecosystem — designed so AI agents/bots, not humans, are the primary user. It layers a stateless MCP proxy on top of its REST API.

GoQuest overview diagram: AI Agent connects via MCP to goquest-iim, which forwards REST to goquest in the neunexus cluster; goquest writes state to Postgres and Redis

goquest / overview.yaml

01

Who reaches goquest, and how

context.json → default

The outside view — goquest treats AI agents as its primary user, with humans (admins, customers) and GitHub webhooks connecting alongside them to the same hub.

GoQuest system context diagram: AI Agent, customer, GitHub connect to goquest via MCP/magic link/webhook; goquest fans out to SpiceDB, lymphhub, Postgres, Redis, cogito, brain

goquest / context.yaml

02

How cmd/service is decomposed internally

components.json → structure

The inside view — the only two entry points that touch users directly are goquest-ui (humans) and goquest-iim (AI agents), and both converge on the single cmd/service REST API. The ticket domain is the system's core; auth/spicedb gates every request; queue (Redis Streams) separates domain logic from async follow-up work.

GoQuest component structure diagram: cmd/service fans out to domain services (ticket, workspace/project), auth, queue, audit; edges to Postgres, spicedb, Redis

goquest / component-structure.yaml

03

Which cluster, which path it ships through

deploy.json → network

Runs on the neunexus cluster (kubeadm K8s on OpenStack Dalmatian, Calico VXLAN), fronted by an Octavia LB + Traefik Ingress, deployed via ArgoCD GitOps. Secrets never live in plaintext manifests — Vault + the Vault Secrets Operator (VSO) sync them into K8s Secrets.

GoQuest infra and network topology diagram: Internet through router and OpenStack Octavia LB into neunexus cluster, node groups, goquest namespace and its dependencies, external LLM services

goquest / infra-network.yaml

04

What tables the data lives in, and how they connect

erd.json → tables/relations

Based on the real migrations — 23 tables and 24 relations centered on the workspaces→projects→tickets hierarchy, plus auth, VCS, references, tags, templates, gamification, and audit logs. archview has no dedicated table node type, so each column list (name:type, PK marked) is folded into a multi-line box label instead.

GoQuest ERD diagram: 23 database tables grouped by tenancy/ticket/tag-template/auth-device/vcs, connected by 24 foreign-key relations, each table box listing its columns and primary keys

goquest / erd.yaml

05

How a commit becomes a deployment

deploy.json → cicd

A git push webhook triggers toji-ci (Tekton), which delegates the build to dagger-engine, pushes the image to the registry, and writes the manifest back to toji-cd (ArgoCD) in the same step — CI-native deployment with no polling delay.

GoQuest CI/CD pipeline diagram: git push webhook triggers toji-ci Tekton, which delegates build to dagger-engine and writes manifests back to toji-cd ArgoCD, which syncs to the cluster

goquest / cicd-pipeline.yaml

06

Where secrets come from, and how they reach a pod

deploy.json → secrets

No plaintext secrets in manifests. A K8s ServiceAccount authenticates to the Vault Secrets Operator (VSO) via VaultAuth; VSO reads Vault and syncs into a K8s Secret, which goquest mounts only as env/volume.

GoQuest secrets flow diagram: K8s ServiceAccount authenticates to Vault Secrets Operator, which reads Vault and syncs to a K8s Secret that goquest mounts as env/volume

goquest / secrets-flow.yaml

07

Which layers a single request passes through

techstack.json → api_layers

A three-tier stack: a Go backend (REST, raw SQL, no ORM), a React/Refine admin UI, and a TypeScript MCP proxy. Humans enter through the admin UI, AI agents through the MCP proxy — both converge on the same Go REST API.

GoQuest API request pipeline diagram: request flows through layered steps from entry to persistence

goquest / api-layers.yaml

08

How the REST API is grouped

techstack.json → api_endpoints

The REST surface splits into four groups under root: tickets, workspaces, vcs, and auth — covering ticket CRUD/state transitions, workspace/project management, VCS integration, and authentication respectively.

GoQuest API endpoint groups diagram: root branches into tickets, workspaces, vcs, and auth endpoint groups

goquest / api-endpoints.yaml

09

Where an AI agent's create-ticket request goes

dataflows.json → flow (create-ticket)

A representative scenario: one MCP request flows through REST validation → the domain service → a Postgres write → a Redis event publish.

GoQuest create-ticket dataflow diagram: MCP request flows through REST validation, domain service, Postgres write, Redis publish

goquest / dataflow-create-ticket.yaml

10

How a ticket state transition gets validated

dataflows.json → flow (state-transition)

A status change only commits if it passes a hardcoded state machine — an invalid transition is rejected at the domain layer.

GoQuest state-transition dataflow diagram: a ticket status change request is validated against a hardcoded state machine before commit

goquest / dataflow-state-transition.yaml

rendered via archview · d2lang/d2 · ELK layout