Frontend Project Structure

Modern React application with TypeScript, organized for scalability and developer experience.

📁 Directory Structure

front/
├── public/               # Static assets (favicon, images)
├── src/
│   ├── components/       # React components
│   │   ├── features/     # Feature-specific components
│   │   │   ├── tasks/    # Task management UI
│   │   │   ├── chat/     # AI chat interface
│   │   │   └── abraxas-timeline/  # Workflow visualization
│   │   ├── layout/       # App structure (Sidebar, AppShell)
│   │   └── ui/           # Reusable UI components
│   ├── hooks/            # Custom React hooks
│   │   ├── useAbraxas.ts # Workflow monitoring
│   │   └── useChatCompletion.ts  # AI chat integration
│   ├── pages/            # Page components (file-based routing)
│   │   ├── Home.tsx      # Dashboard/landing page
│   │   ├── Tasks.tsx     # Task management
│   │   └── Chat.tsx      # AI conversation
│   ├── stores/           # Zustand state management
│   │   ├── userStore.ts  # User authentication state
│   │   └── taskStore.ts  # Task management state
│   ├── theme/            # Design system configuration
│   │   ├── whitelabel.config.ts  # Brand customization
│   │   └── mantine.theme.ts      # Component styling
│   ├── types/            # TypeScript definitions
│   │   └── openapi.ts    # Auto-generated API types
│   └── routes.tsx        # React Router v7 configuration
├── package.json          # Dependencies and scripts
└── vite.config.ts        # Build configuration

🏗️ Architecture Overview

Component Organization:

Pages → Features → UI Components
  ↓
Hooks → Stores → API Types

Key Patterns:

• pages/ - One file per route, handles layout and data fetching
• components/features/ - Business logic components grouped by domain
• components/ui/ - Pure, reusable UI components
• hooks/ - Custom logic extraction for reusability
• stores/ - Global state management with Zustand

🛣️ Routing System

File-based routing with React Router v7:

// routes.tsx
export default [
  layout("./components/layout/AppLayout.tsx", [
    route("/", "pages/Home.tsx"),
    route("/tasks", "pages/Tasks.tsx"), 
    route("/chat", "pages/Chat.tsx"),
  ]),
] satisfies RouteConfig;

URL structure:

/                  → Home dashboard
/tasks             → Task management interface
/chat              → AI conversation
/ocr               → Document processing
/embedding         → Semantic search

🎨 Component Architecture

Feature Components:

// components/features/tasks/TaskList.tsx
export function TaskList() {
  const { tasks, loading } = useTaskStore()
  
  if (loading) return <TaskSkeleton />
  
  return (
    <div className="space-y-3">
      {tasks.map(task => (
        <TaskItem key={task.id} task={task} />
      ))}
    </div>
  )
}

UI Components:

// components/ui/LoadingButton.tsx  
export function LoadingButton({ loading, children, ...props }) {
  return (
    <Button {...props} disabled={loading}>
      {loading && <Loader size="sm" />}
      {children}
    </Button>
  )
}

🔗 API Integration

Type-safe API calls with auto-generated types:

// Generated from backend OpenAPI schema
import { client } from '@/types/openapi'
import type { TaskDTO, CreateTaskDTO } from '@/types/openapi'

// Fully typed API operations
const { data, error } = await client.POST('/tasks/', { 
  body: taskData // TypeScript validates this automatically
})

Workflow:

1. Backend changes → OpenAPI schema updates
2. Run npm run generate-api → generates TypeScript types
3. Import and use → get autocomplete and type checking

🗄️ State Management

Zustand stores for global state:

// stores/taskStore.ts
export const useTaskStore = create<TaskState>((set) => ({
  tasks: [],
  loading: false,
  
  fetchTasks: async () => {
    set({ loading: true })
    const { data } = await client.GET('/tasks/my-tasks')
    set({ tasks: data, loading: false })
  }
}))

// Use in components
const { tasks, fetchTasks } = useTaskStore()

🎨 Design System

Mantine + Tailwind CSS for consistent styling:

// theme/whitelabel.config.ts
export const whiteLabelConfig = {
  primaryColor: '#3b82f6',    // Brand color
  appName: 'My Task App',     // App branding
  logo: '/custom-logo.svg'    // Custom logo
}

Component styling:

// Mix Mantine components with Tailwind classes
<Card className="p-4 border border-gray-200 hover:shadow-lg">
  <Button variant="filled" color="blue">
    Mantine Button
  </Button>
</Card>

🛠️ Development Tools

Built-in tooling:

• Vite: Lightning-fast dev server and builds
• TypeScript: Full type safety across the application
• ESLint + Prettier: Code quality and formatting
• React DevTools: Component inspection and debugging

Key commands:

npm run dev          # Start development server
npm run build        # Production build
npm run generate-api # Generate API types from backend
npm run preview      # Preview production build

🔄 Data Flow

Typical data flow:

User Action → Component → Store → API Call → Update State → Re-render

Example: Creating a task

1. User submits form in TaskForm component
2. Component calls taskStore.createTask()
3. Store makes API call with client.POST()
4. Store updates tasks array with new task
5. TaskList component re-renders with new data

🎯 Key Design Principles

• Component Composition: Small, focused components that combine well
• Type Safety: TypeScript throughout with auto-generated API types
• State Locality: Keep state as local as possible, use stores for shared data
• Feature Organization: Group related components, hooks, and types together

This structure scales from simple pages to complex applications while maintaining clarity and performance.