Getting Started

Architecture

How Urmate request flow, dashboards, APIs, services, database, and integrations fit together.

Urmate uses Next.js App Router with server route handlers, Prisma, Better Auth, and feature-specific service modules.

Request Flow

Browser
  -> app/(routes) page
  -> components/*
  -> app/api route handler
  -> lib/* service
  -> Prisma / external provider / runtime service

Layer	Path	Responsibility
Pages	`app/(routes)`	User-facing routes and route groups.
APIs	`app/api`	Server route handlers, webhooks, provider proxies, runtime controls.
UI	`components`	Dashboard shells, feature pages, shared UI primitives.
Domain logic	`lib`	Business logic, auth, Prisma access, XRouter, study, chat, infra, runtime helpers.
Database	`prisma/schema.prisma`	Relational schema.
Scripts	`scripts`	Dev servers, sync jobs, relay scripts.

Shell	File
Main dashboard	`components/dashboard/dashboard-sidebar.tsx`
Study	`components/dashboard/study-sidebar.tsx`
Instructor	`components/dashboard/study-instructor-sidebar.tsx`
Study Admin	`components/dashboard/study-admin-sidebar.tsx`
Chat	`components/chat-dashboard/chat-sidebar.tsx`
XRouter	`components/dashboard/xrouter-sidebar.tsx`
Cloud Infrastructure	`components/dashboard/cloudinfrastructure-sidebar.tsx`
Game Builder	`components/dashboard/game-builder-sidebar.tsx`
Code Tutor	`components/dashboard/code-tutor-sidebar.tsx`
Platform Admin	`components/admin/admin-sidebar.tsx`

Auth is handled by Better Auth:

Server-side access checks are required for admin, instructor, billing, runtime, and secret-bearing APIs.

Integration	Pattern
Telegram/Discord/Meta	Provider records + webhook receiver + channel agent runtime.
Google Calendar	Instructor OAuth flow with separate Calendar client.
XRouter	Provider registry + model catalog + OpenAI/Anthropic-compatible endpoints.
Builder/Game/Code runtimes	Runtime session records + start/stop APIs + external process/service.
VPS infra	Relay service + heartbeat + command/file/port APIs.
Circles	SSO/session/avatar bridge + optional separate hosted app.

Environment

Important Urmate environment variables grouped by feature area.

Routes and Pages

Human-readable map of Urmate public, dashboard, study, instructor, chat, and tool routes.