菜单
Domain knowledge for the UnifAI frontend. React/TypeScript SPA with feature-oriented layout. Use when working on files under ui/client/src/.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | ui-knowledge |
| description | Domain knowledge for the UnifAI frontend. React/TypeScript SPA with feature-oriented layout. Use when working on files under ui/client/src/. |
| paths | ui/client/src/** |
React 18 SPA (~280 TS/TSX files) with Nginx reverse proxy. Feature-oriented layout (NOT hexagonal).
| Path prefix | Module | Files | Description |
|---|---|---|---|
api/ | API Layer | ~19 | Typed API modules, one per backend target service |
components/agentic-ai/ | Agentic AI | ~51 | Graph builder, chat, templates, inventory |
components/ui/ | shadcn/ui | ~51 | Radix-based UI primitives (Button, Dialog, Select, etc.) |
components/shared/ | Shared | ~22 | FieldRenderer, ShareWorkflow, common widgets |
hooks/ | Custom Hooks | ~23 | Domain hooks (sessions, graphs, workspace, etc.) |
contexts/ | React Contexts | 7 files / 8 contexts | Auth, Theme, View, Shared, Notification, AgenticAI, Streaming, Project |
http/ | HTTP Clients | 4 | Axios instances for each backend service |
features/ | Feature Modules | ~22 | Slack, docs, configuration slices |
pages/ | Pages | ~12 | Route-level page components |
types/ | Types | ~8 | Shared TypeScript types (graph, session, workspace, templates) |
| Client | File | Base URL | Target |
|---|---|---|---|
queryClient | http/queryClient.ts | /api1 | RAG |
axiosAgentConfig | http/axiosAgentConfig.ts | /api2 | MAS |
authClient | http/authClient.ts | /api3 | Identity |
backendClient | http/backendClient.ts | /api4 | Platform |
QueryClientProvider → ThemeProvider → AuthProvider → SharedProvider
→ ViewProvider → ProjectProvider → NotificationProvider → routes
Route-scoped: AgenticAIProvider (agentic routes)
StreamingDataProvider (chat/execution views)
| Context | Hook | Key Responsibility |
|---|---|---|
AuthContext | useAuth | Session, login/logout, token refresh, X-Authenticated-User |
ViewContext | useView | Private vs team workspace, selected team, user groups |
ThemeContext | useTheme | Dark/light toggle, primary color CSS vars |
AgenticAIContext | useAgenticAI | Resource UUID↔name maps, validation caches (~760 LOC) |
StreamingDataContext | useStreamingData | In-memory node stream map for live graph/chat |
NotificationContext | useNotifications | Share invites (received/sent), accept/decline |
| Hook | Domain | Summary |
|---|---|---|
useWorkspaceIdentity | Identity | Single source of truth for userId, identityType, displayName |
useSessionStream | Streaming | NDJSON Redis stream: submit → subscribe → reconnect |
useSessionHub | Sessions | Shared session list/CRUD/execution |
useGraphCreationLogic | Graph | Canvas state, YAML, validation, save/update (~1471 LOC) |
useGraphCreationCanvas | Graph | JointJS paper sync for creation canvas |
useGraphDisplay | Graph | Read-only JointJS + live status overlays |
useTemplates | Templates | List, detail, schema, validate, materialize |
useWorkspaceData | Inventory | Category-based element CRUD |
| Path | Target | Notes |
|---|---|---|
/api1/* | RAG (port 13457) | Standard proxy |
/api2/* | MAS (port 8002) | Streaming: 600s timeout, proxy_buffering off |
/api3/* | Identity | 307 redirect to IDENTITY_HOST |
/api4/* | Platform (port 8005) | Standard proxy |
For full endpoint catalog (72 endpoints), component details, and hook documentation:
.cursor/unifai-dev-guide/docs/services/ui.md.cursor/unifai-dev-guide/guide-index.yaml (maps ui/client/src/** to ui.md).cursor/unifai-dev-guide/source-map.yaml → ui (API modules, hooks, contexts, HTTP clients)| Landmark | Location |
|---|---|
| App entry | App.tsx, main.tsx |
| Route definitions | pages/ |
| API client setup | http/ |
| Build config | vite.config.ts, tailwind.config.ts |
| Nginx config | ui/deployment/nginx.conf.template |
| Proxy config (dev) | ui/vite.config.ts |
Frontend-specific conventions. Note: UI does NOT follow hexagonal architecture — it uses feature-oriented layout instead.
Each feature is self-contained in its directory with its own components,
hooks, and types. Shared code lives in top-level components/, hooks/,
contexts/, and lib/.
All backend communication goes through the api/ layer. Components never
make direct HTTP calls. Hooks wrap API functions and use TanStack React Query v5
for server state management.
All API responses, component props, and state shapes have explicit TypeScript
interfaces. No any types in production code. Shared types in types/.
useWorkspaceIdentity() is the single source of truth for userId, identityType
(user vs team), and displayName. It feeds API params for every identity-scoped call.
Backed by AuthContext (session) + ViewContext (team switching).
components/ui/ — do not reinventNDJSON streaming via native fetch + ReadableStream (not axios).
useSessionStream hook handles submit → subscribe → reconnect.
StreamingDataContext holds Map<nodeId, NodeEntry> for live graph overlays.
Two modes: Creation (useGraphCreationLogic + useGraphCreationCanvas) and
Display (useGraphDisplay). YAML-backed with dagre auto-layout.
Team mode adds edit locks — one editor per blueprint at a time.
These patterns are established and reviewers MUST NOT flag them as violations:
| Pattern | Where it exists | Why it's acceptable |
|---|---|---|
| Feature-oriented layout instead of hexagonal architecture | Entire ui/client/src/ | React SPA — hex doesn't apply; features, hooks, contexts replace ports/adapters |
| Large context files (700+ LOC) | AgenticAIContext (~760 LOC) | Client-side cache + validation orchestration; splitting fragments tightly coupled state |
| Large hooks (1400+ LOC) | useGraphCreationLogic (~1470 LOC) | Graph builder state machine; complexity is inherent, not decomposable without prop-drilling |
AgenticAIContext calls API/axios directly (bypasses hook layer) | contexts/AgenticAIContext.tsx | Resource maps and validation caches require batch fetching at context init; hook indirection adds no value |
AuthContext uses http/authClient directly | contexts/AuthContext.tsx | Auth is the boundary — session management can't go through a domain API layer |
Some components import @/api/* without hook wrappers | TeamSettingsModal, SharedPanel, etc. | Simple one-off API calls where a hook would be trivial; TanStack React Query adoption is partial |
| Nested provider tree (7–8 contexts deep) | App.tsx | Standard React cross-cutting state; each context has a clear single responsibility |
Streaming via native fetch (not Axios) | useSessionStream | NDJSON streaming requires ReadableStream API; Axios doesn't support streaming reads |
MAS domain knowledge — architecture, component routing, rules, recipes. Use when working on any file under multi-agent/.
Project overview and domain routing table for the UnifAI monorepo. Each domain has its own skill with `paths` scoping for auto-surfacing when editing relevant files.
Deep investigation techniques for architecture reviews — import chain tracing, constructor audits, error propagation, cross-reference validation, test hygiene. Load during pipeline reviews or detailed architectural analysis.
Domain knowledge for the Platform Backend service. Admin config, platform API, and core orchestration. Use when working on files under backend/.
Domain knowledge for the Celery worker service. Async task execution for RAG pipeline processing. Shares codebase with rag/ — see RAG domain for core logic.
Domain knowledge for the global_utils shared Python library. Provides cross-service utilities: config, Redis, ports, helpers, embedding, Flask, and Celery app setup. Use when working on files under global_utils/.