Frontend Architecture

Overview

The Axiom Genesis Frontend is a Next.js-based web application that provides users with an intuitive interface for designing pages, workflows, and managing data. Built with modern web technologies (React 18, TypeScript, Redux), it enables both technical and non-technical users to create enterprise applications visually.

Current Status: ✅ Production-Ready | Future: 🚀 Enhanced AI-assisted UI generation

Current Technology Stack ✅

Component	Technology	Purpose
Framework	Next.js 14	Server-side rendering, API routes, optimization
UI Library	React 18	Component-based UI with hooks
State Management	Redux Toolkit	Persistent app state (auth, tenant, navigation)
Data Fetching	React Query	Async data, caching, synchronization
Language	TypeScript	Type safety and developer experience
Styling	CSS Variables + Tailwind	Theming, responsive design
Forms	Custom + React Hook Form	Dynamic form generation and validation
Build	Next.js Webpack	Production optimization and bundling

Project Structure

frontend/
├── src/
│   ├── app/                        # Next.js App Router pages & routes
│   │   ├── page.tsx               # Home page
│   │   ├── dashboard/             # Dashboard pages
│   │   ├── page-designer/         # Page design interface
│   │   ├── workflow-designer/     # Workflow design interface
│   │   ├── dataview/              # Data view configuration
│   │   └── api/                   # API routes (auth, webhooks)
│   │
│   ├── components/                 # React components organized by feature
│   │   ├── viewer/                # Form, Report, Dashboard renderers
│   │   │   ├── FormRenderer.tsx
│   │   │   ├── ReportRenderer.tsx
│   │   │   ├── DashboardRenderer.tsx
│   │   │   └── DataViewRenderer.tsx
│   │   │
│   │   ├── designer/              # Page/Workflow/DataView designers
│   │   │   ├── PageDesigner/
│   │   │   ├── WorkflowDesigner/
│   │   │   └── DataViewDesigner/
│   │   │
│   │   ├── common/                # Reusable components
│   │   │   ├── Button/
│   │   │   ├── Input/
│   │   │   ├── Modal/
│   │   │   ├── Sidebar/
│   │   │   └── Navbar/
│   │   │
│   │   ├── field-components/      # Form field types
│   │   │   ├── TextField/
│   │   │   ├── SelectField/
│   │   │   ├── DateField/
│   │   │   ├── FileField/
│   │   │   └── [15+ more types]
│   │   │
│   │   └── layout/                # Layout components
│   │       ├── MainLayout/
│   │       └── AuthLayout/
│   │
│   ├── context/                    # Context API providers
│   │   ├── ThemeContext.tsx       # Dark mode, color scheme
│   │   ├── TenantContext.tsx      # Tenant information
│   │   └── FeatureContext.tsx     # Feature flags
│   │
│   ├── hooks/                      # Custom React hooks
│   │   ├── useRedux.ts            # Redux selectors/dispatch
│   │   ├── useWorkflowDraft.ts   # Workflow state management
│   │   ├── usePageConfig.ts       # Page configuration hooks
│   │   ├── useForm.ts             # Form handling
│   │   └── [10+ more hooks]
│   │
│   ├── lib/                        # Utilities & helpers
│   │   ├── apiClient.ts           # Axios instance with interceptors
│   │   ├── validators.ts          # Validation functions
│   │   ├── form-builder.ts        # Form generation utilities
│   │   └── transformers.ts        # Data transformation helpers
│   │
│   ├── services/                   # API service layer
│   │   ├── api.ts                 # Base API client setup
│   │   ├── auth.service.ts        # Login, logout, token refresh
│   │   ├── page.service.ts        # Page configuration endpoints
│   │   ├── workflow.service.ts    # Workflow endpoints
│   │   ├── dataview.service.ts    # DataView endpoints
│   │   └── [10+ domain services]
│   │
│   ├── store/                      # Redux Toolkit store
│   │   ├── index.ts               # Store configuration
│   │   ├── slices/
│   │   │   ├── authSlice.ts       # Auth state & actions
│   │   │   ├── tenantSlice.ts     # Tenant state
│   │   │   ├── uiSlice.ts         # UI state
│   │   │   ├── workflowSlice.ts   # Workflow draft
│   │   │   └── [5+ more slices]
│   │   └── hooks.ts               # useAppDispatch, useAppSelector
│   │
│   ├── types/                      # TypeScript definitions
│   │   ├── common.ts              # Common types
│   │   ├── page.ts                # Page & form types
│   │   ├── workflow.ts            # Workflow types
│   │   ├── dataview.ts            # DataView types
│   │   └── [5+ more type files]
│   │
│   └── styles/                     # Global styles
│       ├── globals.css            # Global styles & CSS variables
│       ├── theme.css              # Theme definitions
│       └── [component-specific]
│
├── public/                         # Static assets
├── .env.local                     # Environment variables
├── next.config.js                 # Next.js configuration
├── tsconfig.json                  # TypeScript configuration
├── package.json
└── jest.config.js                 # Testing configuration

Key Components

Page Renderer ✅ Production with Framework Integration

Renders forms, dashboards, reports, and content pages from JSON configurations with integrated frameworks.

NEW (March 14, 2026): Framework integration layer for calculated fields, cascade selects, async validation, and repeater discovery.

// src/components/viewer/FormRenderer/FormRenderer.tsx
interface FormRendererProps {
  pageSchema: PageSchema;
  data?: Record<string, any>;
  mode: 'view' | 'edit' | 'readonly';
  onSubmit?: (data: any) => Promise<void>;
}

export const FormRenderer: React.FC<FormRendererProps> = ({ 
  pageSchema, 
  data, 
  mode, 
  onSubmit 
}) => {
  // Use integrated frameworks
  const frameworks = useFormRendererFrameworks(pageSchema, data);
  
  // 1. Parse page schema (tabs, sections, fields)
  // 2. Generate form fields with framework enhancements
  // 3. Bind data to form
  // 4. Calculate field values automatically
  // 5. Load cascade options dynamically
  // 6. Apply async validation rules
  // 7. Discover repeater templates
  // 8. Handle form submission with full validation
}

Frameworks Integrated:

✅ Calculated Fields - Real-time calculations
✅ Cascade Selects - Multi-level dropdowns
✅ Async Validation - Real-time validation
✅ Repeater Discovery - Auto-template generation

See Framework Integration Architecture for detailed documentation.

Page Designer ✅ Production

Visual interface for designing page layouts, forms, and dashboards without coding.

Current Features:

✅ Drag-and-drop field placement
✅ Field property configuration
✅ Tab and section management
✅ Validation rule setup
✅ Conditional field display
✅ Real-time preview

Workflow Designer ✅ Production

Visual builder for creating multi-step workflows with conditions and error handling.

Current Features:

✅ Step creation and ordering
✅ Trigger configuration
✅ Condition builder
✅ Action mapping
✅ Error handling paths
✅ Version management

DataView Designer ✅ Production

Configure data display with filtering, sorting, and bulk operations.

Current Features:

✅ Column selection and ordering
✅ Filter criteria setup
✅ Sorting rules
✅ Pagination configuration
✅ Bulk action setup
✅ Export options

State Management

Redux Stores ✅

Persistent application state managed by Redux Toolkit.

// Example: Workflow Draft State
interface WorkflowDraft {
  workflowId: string;
  name: string;
  triggers: Trigger[];
  steps: Step[];
  isDirty: boolean;
  lastSaved: Date;
}

// Example actions
dispatch(updateWorkflowStep({ stepId: 's1', config: {...} }));
dispatch(saveWorkflowDraft());
dispatch(revertWorkflowDraft());

Stored State:

Auth token & user info
Current tenant ID
Workflow draft
Page draft
UI preferences (theme, sidebar state)
Navigation history

React Query Stores ✅

Transient data (server state) managed by React Query.

// Example: Fetch workflow instances
const { data, isLoading, error } = useQuery(
  ['workflows', workflowId],
  () => workflowService.getInstances(workflowId),
  { staleTime: 5 * 60 * 1000 } // 5 minute cache
);

Cached Data:

Paginated records
Workflow instances & logs
Page configurations (read)
User data

API Integration

Service Layer ✅

All API calls abstracted into service layer, never called directly from components.

// src/services/workflow.service.ts
class WorkflowService {
  async getWorkflows(filters?: WorkflowFilter): Promise<Workflow[]> {
    const { data } = await apiClient.get('/api/v1/workflows', { params: filters });
    return data.data;
  }

  async createWorkflow(payload: CreateWorkflowPayload): Promise<Workflow> {
    const { data } = await apiClient.post('/api/v1/workflows', payload);
    return data.data;
  }

  async executeWorkflow(id: string, input: any): Promise<WorkflowInstance> {
    const { data } = await apiClient.post(`/api/v1/workflows/${id}/execute`, { inputData: input });
    return data.data;
  }
}

export const workflowService = new WorkflowService();

API Client Setup ✅

Centralized Axios configuration with automatic tenant header injection.

// src/lib/apiClient.ts
const apiClient = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8008',
  timeout: 30000,
});

// Add tenant ID to all requests
apiClient.interceptors.request.use((config) => {
  const tenantId = store.getState().tenant.id;
  config.headers['x-tenant-id'] = encryptTenant(tenantId);
  return config;
});

// Handle token refresh on 401
apiClient.interceptors.response.use(
  response => response,
  async error => {
    if (error.response?.status === 401) {
      await dispatch(refreshToken());
      return apiClient.request(error.config);
    }
    throw error;
  }
);

Styling & Design System

CSS Variables ✅

Brand system defined as CSS variables for consistent theming.

/* Global color scheme */
:root {
  --color-primary-main: #2563eb;
  --color-primary-light: #60a5fa;
  --color-primary-dark: #1e40af;
  
  --color-success: #10b981;
  --color-warning: #f59e0b;
  --color-error: #ef4444;
  --color-info: #3b82f6;
  
  --color-text-primary: #111827;
  --color-text-secondary: #6b7280;
  --color-background: #ffffff;
  --color-surface: #f9fafb;
  
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
  --spacing-xl: 32px;
}

/* Dark mode */
@media (prefers-color-scheme: dark) {
  :root {
    --color-background: #111827;
    --color-surface: #1f2937;
    --color-text-primary: #f3f4f6;
  }
}

Component Styling ✅

Components use CSS variables for consistency and theming.

// src/components/common/Button/Button.tsx
const ButtonContainer = styled.button`
  background-color: var(--color-primary-main);
  color: white;
  padding: var(--spacing-sm) var(--spacing-md);
  border-radius: 6px;
  font-size: 14px;
  cursor: pointer;
  transition: background-color 0.2s;

  &:hover {
    background-color: var(--color-primary-dark);
  }

  &:disabled {
    background-color: var(--color-text-secondary);
    cursor: not-allowed;
  }
`;

Development Standards

Naming Conventions ✅

Components: PascalCase (FormRenderer.tsx, PageDesigner.tsx)
Hooks: camelCase with 'use' prefix (useRedux.ts, usePageConfig.ts)
Constants: UPPER_SNAKE_CASE (API_TIMEOUT, MAX_FILE_SIZE)
Functions: camelCase (getPageSchema, validateForm)
CSS Classes: kebab-case (.form-field, .designer-panel)

Code Organization ✅

✅ One component per file
✅ Related components grouped in feature folders
✅ Reusable logic extracted into custom hooks
✅ All API calls through service layer
✅ Types exported alongside components

TypeScript Guidelines ✅

✅ Use strict typing (no any)
✅ Define component props with interfaces
✅ Export types for external use
✅ Use path aliases (@/components, @/services)

Performance Best Practices ✅

✅ Lazy load components with React.lazy
✅ Memoize expensive components with React.memo
✅ Use React Query for server state (not Redux)
✅ Implement error boundaries for error handling
✅ Cache API responses appropriately

Future Enhancements 🚀

AI-Assisted UI Generation (Q2 2026)

Natural language UI design - "Create a customer form with name, email, phone"
Automatic component suggestion
Layout optimization based on field types

Real-time Collaboration (Q3 2026)

Multiple users editing same page simultaneously
Real-time sync via WebSockets
Conflict resolution for concurrent changes

Advanced Component Library (Q3 2026)

Custom component creation tool
Reusable component sharing
Component versioning

Performance Optimization (Q4 2026)

Server-side rendering optimization
Image optimization and lazy loading
Code splitting improvements

Middleware Architecture - Backend API layer
Database Schema - Data storage and structure
Page Designer Guide - Using the designer
Deployment Guide - Production setup

Overview​

Current Technology Stack ✅​

Project Structure​

Key Components​

Page Renderer ✅ Production with Framework Integration​

Page Designer ✅ Production​

Workflow Designer ✅ Production​

DataView Designer ✅ Production​

State Management​

Redux Stores ✅​

React Query Stores ✅​

API Integration​

Service Layer ✅​

API Client Setup ✅​

Styling & Design System​

CSS Variables ✅​

Component Styling ✅​

Development Standards​

Naming Conventions ✅​

Code Organization ✅​

TypeScript Guidelines ✅​

Performance Best Practices ✅​

Future Enhancements 🚀​

AI-Assisted UI Generation (Q2 2026)​

Real-time Collaboration (Q3 2026)​

Advanced Component Library (Q3 2026)​

Performance Optimization (Q4 2026)​

Related Documentation​

Overview

Current Technology Stack ✅

Project Structure

Key Components

Page Renderer ✅ Production with Framework Integration

Page Designer ✅ Production

Workflow Designer ✅ Production

DataView Designer ✅ Production

State Management

Redux Stores ✅

React Query Stores ✅

API Integration

Service Layer ✅

API Client Setup ✅

Styling & Design System

CSS Variables ✅

Component Styling ✅

Development Standards

Naming Conventions ✅

Code Organization ✅

TypeScript Guidelines ✅

Performance Best Practices ✅

Future Enhancements 🚀

AI-Assisted UI Generation (Q2 2026)

Real-time Collaboration (Q3 2026)

Advanced Component Library (Q3 2026)

Performance Optimization (Q4 2026)

Related Documentation