Skip to content

Commit 1e197f0

Browse files
George-iamGeorge-iam
authored
Update architecture diagram: add Worker, Cloud Tasks, maintenance (#61)
* Update architecture diagram: add Worker, Cloud Tasks, updated connections - Add Gateway Worker as 4th core Cloud Run service - Add Cloud Tasks (timeout-jobs, reminder-jobs) + Cloud Scheduler (4 cron jobs) - Remove standalone Scheduler service (now Cloud Tasks + Cloud Scheduler) - Update connections: gateway→Pub/Sub→worker→agent-core async pipeline - Clarify MCP as HTTP proxy (no DB) - Add worker→DB connections (shared PostgreSQL) * Sync OpenAPI specs from control-plane (PR#176-178 new endpoints) * Regenerate OpenAPI spec from control-plane (144 paths, includes admin/worker) * Fix OpenAPI: add servers block + trailing newline to match CI generation * Regenerate both OpenAPI specs via export_gateway_openapi.py
1 parent 3779e54 commit 1e197f0

2 files changed

Lines changed: 108 additions & 18 deletions

File tree

‎docs/diagrams/axme-complete-architecture.mmd‎

Lines changed: 24 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -96,16 +96,21 @@ flowchart TB
9696
direction TB
9797

9898
subgraph CORE_SERVICES["Core Services"]
99-
GW["Gateway\nFastAPI — 85+ endpoints\nPublic API surface"]:::gateway
100-
AC["Agent Core\nWorkflow orchestration\nStep dispatch"]:::service
99+
GW["Gateway\nFastAPI — 85+ endpoints\nSync: INSERT + COMMIT + Pub/Sub → 200\nAdmin: /admin/probes/*, /admin/maintenance/*"]:::gateway
100+
WORKER["Gateway Worker\nBackground processing\nPub/Sub push receiver\nLifecycle, threads, webhooks, jobs"]:::service
101+
AC["Agent Core\nWorkflow DAG engine\nStep dispatch + lifecycle"]:::service
101102
AUTH_SVC["Auth Service\nJWT issuance\nAPI key validation"]:::service
102103
end
103104

104105
subgraph SUPPORT_SERVICES["Support Services"]
105-
SCHED["Scheduler\nTick loop\nDeadline enforcement\nRetries"]:::service
106106
TOOLREG["Tool Registry\nAction catalog\nWorkflow compilation"]:::service
107-
POLICY["Policy Engine\nAccess decisions\nConsent checks\nRisk evaluation"]:::service
108-
MCP["MCP Platform\n48 JSON-RPC tools\nMirrors CLI"]:::service
107+
POLICY["Policy Engine\nAccess decisions\nConsent checks"]:::service
108+
MCP["MCP Platform\n48 JSON-RPC tools\nProxy to Gateway REST\nNo DB access"]:::service
109+
end
110+
111+
subgraph INFRA_SERVICES["Infrastructure"]
112+
CLOUD_TASKS["Cloud Tasks\naxme-timeout-jobs (50/s)\naxme-reminder-jobs (20/s)\nPush to Worker (OIDC)"]:::datastore
113+
CLOUD_SCHED["Cloud Scheduler\nworkflow-tick + webhook-tick (1 min)\ndaily-cleanup + weekly-vacuum\nAll with OIDC auth"]:::datastore
109114
end
110115
end
111116

@@ -230,19 +235,23 @@ flowchart TB
230235
PROTOCOL --> GW
231236

232237
%% Gateway ↔ Core Services
233-
GW <--> AC
238+
GW <-->|OIDC HTTP| AC
234239
GW <--> AUTH_SVC
235-
GW --> SCHED
236240
GW --> TOOLREG
237241
GW --> POLICY
238242
CLIENTS --> MCP
239-
MCP --> GW
243+
MCP -->|proxy REST| GW
240244
AC --> TOOLREG
241-
AC --> POLICY
245+
AC -->|dispatch step intents| GW
242246

243-
%% Scheduler connections
244-
SCHED --> T_INTENTS
245-
SCHED --> T_SCHEDJOBS
247+
%% Gateway → Worker → Agent Core (async pipeline)
248+
GW -->|publish intent.created| PUBSUB_TOPIC
249+
PUBSUB_TOPIC -->|push subscription| WORKER
250+
WORKER -->|publish lifecycle events| AC
251+
252+
%% Cloud Tasks + Scheduler
253+
CLOUD_TASKS -->|push TIMEOUT/REMINDER| WORKER
254+
CLOUD_SCHED -->|tick + maintenance| GW
246255

247256
%% Gateway → Delivery
248257
GW --> DELIVERY
@@ -254,19 +263,16 @@ flowchart TB
254263
%% Addressing → Agent Core
255264
ADDR_ROUTING --> AC
256265

257-
%% Gateway → Data
266+
%% Gateway + Worker → Data
258267
GW --> PG_INTENT
259268
GW --> PG_USER
260269
GW --> PG_INBOX
261270
GW --> PG_ENTERPRISE
262271
GW --> PG_WEBHOOK
272+
WORKER --> PG_INTENT
273+
WORKER --> PG_INBOX
263274
AC --> PG_WORKFLOW
264275

265-
%% Pub/Sub
266-
GW --> PUBSUB_TOPIC
267-
AC --> PUBSUB_TOPIC
268-
PUBSUB_TOPIC --> T_PUBSUB
269-
270276
%% Human Tasks
271277
GW --> HUMANTASK
272278
HT_CLI --> GW

‎docs/openapi/gateway.v1.json‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2471,6 +2471,90 @@
24712471
}
24722472
}
24732473
},
2474+
"/internal/jobs/TIMEOUT/{job_id}": {
2475+
"post": {
2476+
"summary": "Internal Job Timeout",
2477+
"description": "Process a TIMEOUT job pushed by Cloud Tasks.",
2478+
"operationId": "internal_job_timeout_internal_jobs_TIMEOUT__job_id__post",
2479+
"parameters": [
2480+
{
2481+
"name": "job_id",
2482+
"in": "path",
2483+
"required": true,
2484+
"schema": {
2485+
"type": "string",
2486+
"title": "Job Id"
2487+
}
2488+
}
2489+
],
2490+
"responses": {
2491+
"200": {
2492+
"description": "Successful Response",
2493+
"content": {
2494+
"application/json": {
2495+
"schema": {
2496+
"type": "object",
2497+
"additionalProperties": true,
2498+
"title": "Response Internal Job Timeout Internal Jobs Timeout Job Id Post"
2499+
}
2500+
}
2501+
}
2502+
},
2503+
"422": {
2504+
"description": "Validation Error",
2505+
"content": {
2506+
"application/json": {
2507+
"schema": {
2508+
"$ref": "#/components/schemas/HTTPValidationError"
2509+
}
2510+
}
2511+
}
2512+
}
2513+
}
2514+
}
2515+
},
2516+
"/internal/jobs/REMINDER/{job_id}": {
2517+
"post": {
2518+
"summary": "Internal Job Reminder",
2519+
"description": "Process a REMINDER job pushed by Cloud Tasks.",
2520+
"operationId": "internal_job_reminder_internal_jobs_REMINDER__job_id__post",
2521+
"parameters": [
2522+
{
2523+
"name": "job_id",
2524+
"in": "path",
2525+
"required": true,
2526+
"schema": {
2527+
"type": "string",
2528+
"title": "Job Id"
2529+
}
2530+
}
2531+
],
2532+
"responses": {
2533+
"200": {
2534+
"description": "Successful Response",
2535+
"content": {
2536+
"application/json": {
2537+
"schema": {
2538+
"type": "object",
2539+
"additionalProperties": true,
2540+
"title": "Response Internal Job Reminder Internal Jobs Reminder Job Id Post"
2541+
}
2542+
}
2543+
}
2544+
},
2545+
"422": {
2546+
"description": "Validation Error",
2547+
"content": {
2548+
"application/json": {
2549+
"schema": {
2550+
"$ref": "#/components/schemas/HTTPValidationError"
2551+
}
2552+
}
2553+
}
2554+
}
2555+
}
2556+
}
2557+
},
24742558
"/v1/intents/{intent_id}/resolve": {
24752559
"post": {
24762560
"summary": "Resolve Intent",

0 commit comments

Comments
 (0)