Design patterns, rules, and procedures for developing GUI features in `apps/web`. Covers migration from `optaic-v0` legacy design and new `ApiClient` integration patterns.
Reference patterns and rules for frontend development in apps/web.
Pattern: "Strict Legacy Replication"
Context: When porting features from optaic-v0, the design must be preserved exactly while replacing the backend implementation.
Reference Material:
v0-ui/next_app (Project Relative)Target Audience: Investment Quant Researchers, Data Engineers, Data Scientists, Risk Quants.
Core Requirements:
GUI development is iterative, not linear.
optaic-v0 reference.ui-ux-tester).
Rule: ALL data access must go through the useApiClient hook.
Prohibited: Direct fetch(), axios, or SWR fetchers without the SDK.
| Feature | Legacy Pattern (optaic-v0) | Modern Pattern (optaic-trading) |
|---|---|---|
| Auth | Implicit Cookie/Session | ApiClient (Header integration) |
| Fetch | fetch('/api/resource') | api.resource.list() |
| State | Ad-hoc React state | React Query (optional) or useEffect + State |
| Types | any / Missing | libs/sdk_ts mapped types |
Components should follow this structure separate logic from presentation where possible, but colocation is accepted for simpler ports.
export const MyComponent = () => {
// 1. Hook Initialization
const api = useApiClient();
const { tenantId } = useSessionStore();
// 2. State
const [data, setData] = useState<DataType | null>(null);
// 3. Effect (Data Loading)
useEffect(() => {
if (!api) return;
api.domain.operation().then(setData);
}, [api]);
// 4. Render
return <div className="legacy-tailwind-classes">...</div>;
};
Use this procedure when porting a component from optaic-v0 to apps/web.
optaic-v0/dev_tools/src/ui/next_app.apps/web/src/components/....next/link, next/router). Replace with react-router-dom.fetch calls.useApiClient.Out types if necessary.[!WARNING] The following patterns violate platform architecture and must be rejected during code review.
pages/api/...). Logic must live in the Python backend (apps/api).fetch() calls in UI components.