Architecture Overview¶
SystemForge Web follows a modular, composable architecture designed for multi-tenant SaaS applications.
Design Principles¶
- Security First - BFF pattern with HTTP-only cookies, no tokens in localStorage
- Composable - Use only the packages you need
- Type Safe - Full TypeScript with strict types
- Framework Agnostic - Works with any React framework
- Backend Agnostic - Works with any backend supporting BFF pattern
System Architecture¶
┌─────────────────────────────────────────────────────────────────────────┐
│ Browser │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ React Application │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │
│ │ │TelemetryProv│ │ ErrorBound │ │ AppShell │ │ │
│ │ │ ider │ │ ary │ │ ┌────────┬──────────┐ │ │ │
│ │ └─────────────┘ └─────────────┘ │ │ Navbar │ Content │ │ │ │
│ │ │ ├────────┤ │ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │Sidebar │ │ │ │ │
│ │ │ AuthProvider│ │TenantProvide│ │ │ │ │ │ │ │
│ │ │ │ │ r │ │ └────────┴──────────┘ │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ ApiProvider │ │QueryClient │ │ │
│ │ │ │ │ Provider │ │ │
│ │ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
│ HTTP (cookies)
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ BFF Proxy Layer │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ /api/auth/* │ │ /api/users/* │ │ /api/orgs/* │ │
│ │ │ │ │ │ │ │
│ │ - POST /login │ │ - GET /me │ │ - GET / │ │
│ │ - POST /logout │ │ - PATCH /me │ │ - POST / │ │
│ │ - POST /refresh│ │ │ │ - GET /:id │ │
│ │ - GET /session │ │ │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ Features: │
│ - HTTP-only cookie management │
│ - CSRF protection │
│ - Token refresh │
│ - Request forwarding to backend │
└─────────────────────────────────────────────────────────────────────────┘
│
│ Internal (JWT)
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ SystemForge Backend │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Identity │ │ Authorization │ │ Multi-tenant │ │
│ │ │ │ │ │ │ │
│ │ - Users │ │ - RBAC │ │ - Organizations│ │
│ │ - Sessions │ │ - SpiceDB │ │ - Memberships │ │
│ │ - OAuth │ │ - Permissions │ │ - Isolation │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
Provider Hierarchy¶
The recommended provider order:
<QueryClientProvider>
{' '}
{/* TanStack Query */}
<BrowserRouter>
{' '}
{/* React Router */}
<TelemetryProvider>
{' '}
{/* Event tracking */}
<ErrorBoundary>
{' '}
{/* Error handling */}
<AuthProvider>
{' '}
{/* Authentication */}
<ApiProvider>
{' '}
{/* HTTP client */}
<TenantProvider>
{' '}
{/* Multi-tenancy */}
<AppShell>
{' '}
{/* Layout */}
<App />
</AppShell>
</TenantProvider>
</ApiProvider>
</AuthProvider>
</ErrorBoundary>
</TelemetryProvider>
</BrowserRouter>
</QueryClientProvider>
Authentication Flow¶
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ User │ │ React │ │ BFF │ │ Backend │
└────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │ │
│ Click Login │ │ │
│───────────────>│ │ │
│ │ POST /auth/login │
│ │───────────────>│ │
│ │ │ Authenticate │
│ │ │───────────────>│
│ │ │ │
│ │ │<───────────────│
│ │ │ JWT tokens │
│ │<───────────────│ │
│ │ Set-Cookie │ │
│ │ (HTTP-only) │ │
│<───────────────│ │ │
│ Redirect │ │ │
│ │ │ │
│ API Request │ │ │
│───────────────>│ │ │
│ │ GET /api/data │ │
│ │ (with cookie) │ │
│ │───────────────>│ │
│ │ │ Forward with │
│ │ │ Bearer token │
│ │ │───────────────>│
│ │ │<───────────────│
│ │<───────────────│ │
│<───────────────│ │ │
Data Flow¶
- User Action → Component calls hook (e.g.,
useAuth().login()) - Hook → Calls API client method
- API Client → Makes HTTP request with cookies
- BFF Proxy → Extracts session, forwards with JWT
- Backend → Processes request, returns response
- Response → Flows back through layers
- State Update → React Query cache updated
- Re-render → UI reflects new state