Guardian’s backend routes aren’t just functional — they’re designed for maximum clarity, traceability, and automation.
Here’s an example:
guardianRoutes.openapi(
createRoute({
method: 'get',
path: '/path-name',
summary: 'Get all the data ...',
description: '',
tags: ['Codegen'],
responses: {
200: {
description: 'This data can change based on conditions and prompt/query',
content: {
'application/json': {
schema: z.object({
message: z.string(),
})
}
}
}
}
}),
withHandler('guardian.generate', async (c) => { ... })
);
Let’s break this down:
🔧 createRoute
: Structured Route Metadata
Each route is wrapped with createRoute()
, which describes:
- HTTP method (
get
,post
, etc.) - Path (
/profile-context
) - Purpose (
summary
,description
) - Tags for organization in API explorers
- Typed response schemas using
zod
✅ This creates a self-documenting, fully typed API — consumable by both humans and machines.
📘 .openapi
: Automatic OpenAPI Spec Generation
By wrapping the route definitions in guardianRoutes.openapi(...)
, Guardian can:
- ✅ Auto-generate an OpenAPI 3.0 compliant schema
- 🤖 Feed this schema to agents for autonomous route discovery
- 🧪 Power type-safe client generation (like SDKs or testing tools)
- 📊 Enable observability + documentation portals instantly
🧠 withHandler
: Global Middleware, Logs, and Tracing
All business logic is wrapped in withHandler(name, handlerFn)
, which:
- 📥 Injects all standard context (auth, clients, telemetry, etc.)
- 📈 Tracks usage for analytics and debugging
- 🪵 Automatically logs execution details (duration, success, error)
- 🔐 Ensures consistent error handling and output formatting
🎯 Think of
withHandler
as the universal controller — the same logic wrapper used for agents, UIs, and external API calls.
🧪 zod
: Fully Typed Inputs and Outputs
Every route uses zod
to:
- 🧬 Define strict schemas for input/output
- 🧠 Auto-generate types for frontend and agents
- 📄 Populate your OpenAPI schema effortlessly
This enforces correctness without relying on runtime guesswork.
💡 Why This Matters
This approach makes Guardian’s routes:
- Typed
- Documented
- Testable
- Observable
- Agent-compatible
And most importantly, it turns your backend into a programmatically navigable API surface, ready to be consumed by your own agents or external tools — without fragile UIs or hardcoded assumptions.
This is the beginning of self-generating feature automation.
Absolutely — here’s the rewritten version that shows exactly how you can wire this in. This is next-level DevOps + automation fuel:
🔁 Auto-Issue Creation + Task Logging from Routes
Every Guardian route is already wrapped in withHandler()
, which gives you a centralized place to plug in side effects like logging, telemetry, and… now autonomous work tracking.
Here’s what you can do:
✅ Add GitHub Issue Creation on Route Calls
Every time a route is called, you can optionally:
- Log the route call as a GitHub issue in a specific repo (e.g.
guardian-logs
) - Use the route name, inputs, and result/error as the issue body
- Apply labels like
auto-logged
,route-call
, ormonitoring
This gives you:
- ✅ A real-time audit log of what your system is doing
- 🔍 Historical traces that are searchable, commentable, and linkable
- 📎 GitHub-native observability — nothing hidden, no black boxes
// Inside withHandler wrapper
await createGitHubIssue({
title: `[ROUTE CALL] ${routeName} @ ${timestamp}`,
body: formatRouteTrace(context, result),
labels: ["auto-logged", "telemetry", "guardian"]
});
📌 Add Task/Memory Logs in Notion or Supabase
You can also automatically:
- Create a new row in your
tasks
orexecutions
table (Supabase) - Or log it as a Notion card on your Guardian Kanban board
- Or add it as a new
memory
viaaddMemory()
tagged withroute_call
This gives you:
- 🎯 Full context traceability across systems
- 🧠 A growing dataset that agents can use to reason about past behavior
- 🔁 A feedback loop between code and cognition
await addMemory({
agent: "guardian",
title: `Route Triggered: ${routeName}`,
content: JSON.stringify(routeInputs, null, 2),
tags: ["route", routeName, "execution"],
type: "execution_trace",
source: "server",
metadata: {
result: summarizeOutput(result),
durationMs: endTime - startTime
}
});
🧠 Why This Matters for Autonomous Systems
This pattern lets your backend routes become cognitive events:
- Every API hit becomes a traceable thought
- Every handler is logged as an intention + result
- You now have ground truth, not just inference
And later, your agents can say:
“I already called
/generate-idea
last Tuesday. Here’s the result. No need to redo it.”
This is the beginning of causal memory + intelligent system introspection.
Leave a Reply