Architecture Guide

Understanding WorkGenius platform architecture

Technology Stack

Frontend

  • • React 18 - UI framework
  • • TypeScript - Type safety
  • • Tailwind CSS - Styling
  • • Shadcn/ui - Component library
  • • React Query - Data fetching
  • • Framer Motion - Animations
  • • React Router - Routing

Backend

  • • Base44 Platform - Backend-as-a-Service
  • • Deno - Serverless functions
  • • PostgreSQL - Database
  • • JSON Schema - Data validation
  • • OAuth - Authentication
Folder Structure
project/
├── pages/                  # Page components (FLAT - no subfolders)
│   ├── Dashboard.jsx
│   ├── ClientManagement.jsx
│   └── TaskManager.jsx
│
├── components/
│   ├── ui/                # UI primitives (shadcn/ui)
│   ├── shared/            # Shared components
│   ├── client/            # Client-specific components
│   ├── sales/             # Sales-specific components
│   ├── receivables/       # Receivables components
│   ├── hooks/             # Custom React hooks
│   ├── utils/             # Utility functions
│   ├── routing/           # Route configuration
│   ├── security/          # Security components
│   └── types/             # TypeScript types
│
├── entities/              # JSON schema definitions
│   ├── Contact.json
│   ├── Invoice.json
│   └── Task.json
│
├── functions/             # Backend Deno functions
│   ├── emailInvoice.js
│   └── processPayment.js
│
└── Layout.jsx             # Global layout wrapper
Data Flow Architecture

1. Client → API

import { base44 } from '@/api/base44Client';

// List entities
const tasks = await base44.entities.Task.list('-created_date', 20);

// Filter entities
const clients = await base44.entities.Contact.filter(
  { status: 'active' }, 
  '-created_date', 
  50
);

// Create entity
await base44.entities.Invoice.create({ 
  invoice_number: 'INV-001',
  total_amount: 1000 
});

2. React Query Caching

import { useQuery } from '@tanstack/react-query';

const { data, isLoading } = useQuery({
  queryKey: ['tasks', userId],
  queryFn: () => base44.entities.Task.list(),
  staleTime: 300000,  // 5 minutes
  gcTime: 600000,     // 10 minutes
  refetchOnWindowFocus: false
});

3. Mutations & Updates

const mutation = useMutation({
  mutationFn: (data) => base44.entities.Task.create(data),
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ['tasks'] });
  }
});
Performance Optimization

Code Splitting

Pages are lazy-loaded using React.lazy() for optimal bundle size

Query Caching

React Query with aggressive caching (5-10 min stale times)

Memoization

useMemo/useCallback for expensive computations

Prefetching

Hover/focus prefetching for anticipated navigation

Security Architecture

Authentication

Base44 built-in auth with JWT tokens

Authorization

Role-based access control (admin/user)

Audit Logging

All sensitive actions logged to AuditLog entity

Data Validation

JSON Schema validation on entity operations

Development Best Practices
Component Design
  • • Keep components under 200 lines
  • • Extract logic into custom hooks
  • • Use shared components for common patterns
  • • Prefer composition over inheritance
State Management
  • • Use React Query for server state
  • • Local state with useState/useReducer
  • • Avoid prop drilling - use composition
  • • Memoize expensive computations
Error Handling
  • • Use Error Boundaries for UI errors
  • • Let errors bubble in queries/mutations
  • • Display user-friendly error messages
  • • Log errors to monitoring service