Skip to main content

​
Engineering Domain

The Engineering domain contains 3 agents specialized in generating TypeScript code for the SO1 platform stack: Hono backend APIs, Next.js frontends, and shared type definitions.

​
Agents

AgentStagePurpose
Hono Backend3API routes, middleware, Zod validation for so1-control-plane-api
Next.js Frontend3React components, App Router patterns for so1-console
TypeScript Shared2Zod schemas, shared types, error envelopes for so1-shared

​
SO1 Technology Stack

Backend

Hono 4
Fast web framework
Zod validation
Drizzle ORM

Frontend

Next.js 16
React 19
TanStack Query
Tailwind CSS 4

Shared

TypeScript 5.7
Zod schemas
Type contracts
Error envelopes

​
When to Use

Use Hono Backend for:
  • REST API endpoints
  • Middleware (auth, logging, CORS)
  • Database queries (Drizzle ORM)
  • Request/response validation (Zod)
  • Error handling
Repository: so1-control-plane-api

​
Typical Workflow

For a new feature (e.g., “User Settings API”):
1

TypeScript Shared (Stage 2)

Define schemas and types:
// so1-shared/src/schemas/user-settings.ts
export const UserSettingsSchema = z.object({
  userId: z.string(),
  theme: z.enum(['light', 'dark', 'system']),
  notifications: z.boolean(),
});
2

Hono Backend (Stage 3)

Implement API endpoint:
// so1-control-plane-api/src/routes/settings.ts
app.get('/api/v1/settings', async (c) => {
  const settings = await db.query.userSettings.findFirst();
  return c.json(settings);
});
3

Next.js Frontend (Stage 3)

Create UI component:
// so1-console/src/app/settings/page.tsx
export default function SettingsPage() {
  const { data } = useQuery({ queryKey: ['settings'] });
  return <SettingsForm data={data} />;
}

​
FORGE Stages

StageAgentsActivities
Stage 2 (Implementation)TypeScript SharedDefine schemas, types, contracts
Stage 3 (Documentation)Hono Backend, Next.js FrontendImplement APIs and UI components

​
Code Standards

​
Hono Backend

// Route pattern
app.post('/api/v1/resource', zValidator('json', ResourceSchema), async (c) => {
  const body = c.req.valid('json');
  // Implementation
  return c.json({ success: true, data: result });
});

​
Next.js Frontend

// Server Component
export default async function Page() {
  const data = await fetchData();
  return <ClientComponent data={data} />;
}

// Client Component
'use client';
export function ClientComponent({ data }: Props) {
  return <div>{data.name}</div>;
}

​
TypeScript Shared

// Zod schema with inference
export const ResourceSchema = z.object({
  id: z.string().startsWith('res_'),
  name: z.string().min(1).max(100),
});

export type Resource = z.infer<typeof ResourceSchema>;

​
Integration Points

All three agents integrate with:
  • Control Plane API endpoints
  • Veritas prompts for patterns
  • GitHub repositories (so1-io org)

​
Best Practices

Always define schemas and types in so1-shared first, then import them in backend and frontend.
Define Zod schemas for all API inputs/outputs. Use .parse() for type safety.
  • Backend: src/routes/ for endpoints
  • Frontend: src/app/ for pages (App Router)
  • Shared: src/schemas/ for Zod schemas
Use standard error envelopes from so1-shared:
return c.json({ success: false, error: { code, message } }, 400);

Hono Backend

API development agent

Next.js Frontend

UI development agent

TypeScript Shared

Schema and type agent