Gui Develop Patterns

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.