Architecture overview - Pinter

Pinter is split into a React frontend and a FastAPI backend. The frontend owns the user interface. The backend owns authentication, persistence, agent configuration, tool resolution, ADK execution, and API routes.

System shape

Main seams

Seam	Interface	Implementation
Frontend API seam	`api`, `stream`, `upload` in `src/shared/auth/authenticated.ts`	Fetch calls with token refresh and `AuthError`.
Route seam	TanStack file routes in `src/routes`	Feature modules under `src/features`.
Agent execution seam	`ADKExecutorV2.execute()`	Agent factory, runner, persister, prompt guard, token usage.
Agent construction seam	`AgentFactoryV2.create_agent()`	DB config loading, instruction merge, model resolution, tool resolution.
Tool resolution seam	`ToolRegistryV2.resolve_tools()`	Built-ins, tool rows, agent tools, MCP toolsets, integrations.
Workflow execution seam	`ADKWorkflowExecutor.execute()`	Graph validation, execution plan, node runners, state, token usage.

These seams are deep modules: callers learn a small interface and get a large amount of behavior behind it.

Request flow

Code map

Area	Path
Frontend routes	`pinter-fe/src/routes`
Frontend features	`pinter-fe/src/features`
Shared frontend modules	`pinter-fe/src/shared`
Backend v2 routes	`pinter-be/routes/v2`
ADK modules	`pinter-be/modules/adk`
Database models	`pinter-be/db/models`