AI-Native RF Module Designer - Architecture

The PCB Stackup Generator uses a two-service architecture — a React frontend and a FastAPI backend communicating via REST/SSE — plus external managed services (Supabase, Gemini API):

┌─────────────────────────────────────────────────────────────┐
│              React Frontend (Vite/TypeScript)                │
│                      Port 5180                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │  Components  │  │    Hooks     │  │    Services      │   │
│  │  (300+ UI)   │  │ (State Mgmt)│  │ (Business Logic) │   │
│  └──────────────┘  └──────────────┘  └──────────────────┘   │
│                            │                                  │
└────────────────────────────┼─────────────────────────────────┘
                             │ HTTP/REST + SSE
                             ▼
                  ┌─────────────────────┐     ┌─────────────────┐
                  │   FastAPI            │     │   External       │
                  │   Port 8000          │────▶│   Services       │
                  │                      │     │                  │
                  │ • Gemini AI Chat     │     │ • Supabase       │
                  │   (agent loop, SSE)  │     │   (auth + DB)    │
                  │ • RF Projects        │     │ • Gemini API     │
                  │ • Components         │     │ • Nexar API      │
                  │ • Materials          │     └─────────────────┘
                  │ • KiCad Export       │
                  │ • ODB++/ADS/Gerber   │
                  │ • IPC-2581/HFSS      │
                  └─────────────────────┘

There is no separate Node.js backend — chat, knowledge/RAG, and all exports run inside the FastAPI service (see the note under Backend Architecture).

Frontend Architecture

Component Structure

frontend/src/
├── components/              # React UI components (300+ files)
│   ├── Chat/               # AI chat components
│   │   ├── EmptyState.tsx        # Starter prompt cards (6 clickable, 2-col grid)
│   │   ├── ActionCard.tsx        # Inline tool call result cards
│   │   └── MessageBubble.tsx     # Chat messages with action card rendering
│   ├── Layout/
│   │   └── GeminiSidebar.tsx     # Chat sidebar (auto-open, welcome)
│   └── ...
├── hooks/                  # Custom React hooks (10+ files)
├── services/               # Business logic services (120+ files)
│   ├── chat/               # Chat services
│   │   ├── suggestionService.ts    # Starter prompt suggestions
│   │   └── geminiToolCallHandler.ts # Tool call dispatch (incl. apply_design_template)
│   └── ...
├── contexts/               # React contexts (5 files)
├── utils/                  # Utility functions (115+ files)
├── types/                  # TypeScript definitions
└── constants/             # Application constants

Design Patterns

1. Service Layer Pattern: Business logic extracted from components into services.
2. Hook-Based State Management: Custom hooks encapsulate state logic.
3. Context Splitting: Multiple focused contexts instead of one monolithic context.
4. Barrel Exports: Centralized exports from index files.

Backend Architecture

FastAPI Backend (Port 8000)

backend/
├── main.py                 # FastAPI application entry point
├── routes/                  # API route handlers (~33 modules; see CLAUDE.md for the domain grouping)
├── services/               # Business logic services (split into packages: solver/, compliance/, component_search/, rf_chain/, stackup_pdf/, surrogate/, test_coupon/, nexar/, pdf/, pptx_generator/)
├── tools/                  # Agent-loop tool handlers (10 active tools + `run_solver` alias)
├── agents/                 # AI selection agents (9 agents: 8 simple_*_agent + material_selection_agent, plus base_agent + scoring helpers)
├── agent_router_config.py  # Component-type → agent routing table
├── utils/                  # Utility modules (incl. `kicad/` package for symbol/schematic/pcb/stackup generators)
└── categorized_databases/  # Component JSON databases (~20 category dirs)

AI Chat (Gemini) is handled by the FastAPI backend at port 8000 — see backend/services/gemini_chat_service.py, the gemini_chat_prompts/ and agent_loop/ packages (the loop itself is agent_loop/loop.py), agent_loop_sse.py, and tool_dispatcher.py. The agent-loop streams over SSE at POST /api/chat/gemini/stream. There is no separate Node.js backend; legacy package.json scripts referencing index.js are inactive.

Data Flow

RF Module Generation Flow

1. User Input (Frontend)
2. Component Selection (frontend/src/services/rfChain/designService.ts + chainMapper/)
3. Power Flow Calculation (frontend/src/services/rfChain/powerFlowCalculatorService.ts)
4. KiCad Project Generation (backend/utils/kicad_export.py + backend/utils/kicad/)
5. ZIP Download (Frontend)

Stackup Generation Flow

1. User Configuration (Frontend)
2. Stackup Generation (stackupGenerator.ts)
3. Validation (DfmValidator.ts)
4. Export Options (KiCad, ADS, ODB++, Gerber, IPC-2581, HFSS, MagicON Internal, PDF)

AI Chat Onboarding Flow

1. First visit → Chat sidebar auto-opens with welcome message
2. User clicks starter prompt card or types question
3. Gemini processes request with enhanced system prompt (design templates, phase context)
4. Response rendered with inline ActionCards for tool calls
5. Live agent: the AI-native shell (/app/agent) streams a multi-turn tool-call loop (scripted demo mode removed; the public signed-out /demo/agent replay is shipped — backend/routes/demo.py + frontend/src/components/Demo/, flags FF_PUBLIC_DEMO/VITE_FF_PUBLIC_DEMO)

Performance Optimizations

• Request Deduplication: Prevents duplicate API calls.
• Database Preloading: Component database loads at server startup.
• Component Caching: Frontend and backend caching.
• Context Memoization: Split contexts reduce unnecessary re-renders.

Security

• HTTPS Enforcement: Production redirects to HTTPS.
• CORS Configuration: Environment-specific origins.
• Security Headers: HSTS, CSP, X-Frame-Options.
• Input Validation: Pydantic models for all API inputs.