GUI Development Patterns

Reference patterns and rules for frontend development in apps/web.

1. Design Reference Pattern

Pattern: "Strict Legacy Replication" Context: When porting features from optaic-v0, the design must be preserved exactly while replacing the backend implementation.

Reference Material:

• Legacy Codebase: v0-ui/next_app (Project Relative)
• Target Aesthetic: Tailwind CSS classes must match the legacy source to ensure visual consistency.

2. Design Philosophy & User Persona

Target Audience: Investment Quant Researchers, Data Engineers, Data Scientists, Risk Quants.

Core Requirements:

• Simplism & Modernity: Clean, distraction-free, professional "FinTech" aesthetic.
• Density w/ Digestibility: High information density (grids, charts) but easy to scan.
• Interactive: Keyboard shortcuts (Esc, Enter, /) are mandatory for power users.
• Action-Oriented: Controls must be intuitive and immediately accessible.

3. The Iterative Development Process

GUI development is iterative, not linear.

1. Develop: Port/Build using optaic-v0 reference.
2. Verify: QA using Browser (Agent ui-ux-tester).
   • Check: Alignment, Responsiveness, Data Binding.
3. Report: Generate QA Report (UX Polish, Missing Backend Features).
4. Refine: Fix issues, improve UX, strictly ignoring backend limitations (report them instead).
5. Approve: Mark as "Production Ready".

4. Architecture Patterns

Data Fetching Pattern

Rule: ALL data access must go through the useApiClient hook. Prohibited: Direct fetch(), axios, or SWR fetchers without the SDK.

Component Structure Pattern

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>;
};

3. Migration Procedure

Use this procedure when porting a component from optaic-v0 to apps/web.

1. Selection: Identify the target component in optaic-v0/dev_tools/src/ui/next_app.
2. Transplant: Copy the component file to apps/web/src/components/....
3. Sanitization:
   • Remove Next.js specific imports (next/link, next/router). Replace with react-router-dom.
   • Remove all fetch calls.
4. Integration:
   • Inject useApiClient.
   • Re-implement data fetching using SDK methods.
   • Map legacy data shapes to SDK Out types if necessary.
5. Refinement: Ensure Tailwind classes render correctly in the Vite environment.

4. Anti-Patterns (Blocking Rules)

[!WARNING] The following patterns violate platform architecture and must be rejected during code review.

• Backend Route Copying: Do NOT copy Next.js API routes (pages/api/...). Logic must live in the Python backend (apps/api).
• Raw Fetch: No fetch() calls in UI components.
• Style Deviation: Do not "improve" the design unless explicitly requested. Start with strict parity.