Skip to main content

Frontend Project Structure

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

📁 Directory Structure​

apps/frontend/
├── public/               # Static assets (favicon, images)
├── src/
│   ├── app/              # Next.js App Router (pages & layouts)
│   │   ├── layout.tsx    # Root layout
│   │   ├── page.tsx      # Home page
│   │   ├── chat/         # Chat page
│   │   ├── abraxas/      # Abraxas workflow page
│   │   ├── embedding/    # Embedding search page
│   │   └── ocr/          # OCR page
│   ├── components/       # React components
│   │   ├── features/     # Feature-specific components
│   │   │   ├── chat/     # AI chat interface
│   │   │   └── abraxas-timeline/  # Workflow visualization
│   │   ├── app-sidebar.tsx  # Application sidebar
│   │   ├── site-header.tsx  # Site header
│   │   ├── providers.tsx    # React Query & other providers
│   │   └── ui/           # ShadCN UI components
│   │       ├── button.tsx
│   │       ├── card.tsx
│   │       └── ...       # Other Radix UI components
│   ├── hooks/            # Custom React hooks
│   │   ├── useAbraxas.ts # Abraxas workflow management
│   │   └── useChatCompletion.ts  # AI chat integration
│   ├── api/              # API client & types
│   │   ├── requests/     # Auto-generated API client
│   │   └── queries/      # TanStack Query hooks
│   ├── lib/              # Utility functions
│   │   └── utils.ts      # cn() and other helpers
│   └── types/            # TypeScript definitions
├── components.json       # ShadCN configuration
├── next.config.ts        # Next.js configuration
├── tailwind.config.js    # Tailwind configuration
└── package.json

🏗️ Architecture Overview​

Component Organization:

App Router (pages) → Features → UI Components
  ↓
Hooks → TanStack Query → API Types

Key Patterns:

  • app/*/page.tsx - Next.js pages with App Router
  • app/layout.tsx - Root layout with providers
  • components/features/ - Business logic components grouped by domain
  • components/ui/ - ShadCN components (Radix UI primitives)
  • hooks/ - Custom logic extraction for reusability
  • api/queries/ - TanStack Query hooks for data fetching

🛣️ Routing System​

App Router with Next.js 15:

src/app/
├── layout.tsx          → Root layout (wraps all pages)
├── page.tsx            → / (Home page)
├── chat/
│   └── page.tsx        → /chat
├── abraxas/
│   └── page.tsx        → /abraxas
├── embedding/
│   └── page.tsx        → /embedding
└── ocr/
    └── page.tsx        → /ocr

URL structure:

/                  → Home dashboard
/chat              → AI conversation
/ocr               → Document processing
/embedding         → Semantic search
/abraxas           → Workflow timeline

Benefits of App Router:

  • Server and client components
  • Built-in layouts and loading states
  • Simplified data fetching
  • Better TypeScript support

💾 Data Flow Architecture​

How data moves through the application:

User Input → Component → TanStack Query → API Call → Backend
                ↓
UI Update ← Component ← Query Cache ← API Response ← Backend

File organization by data flow:

  • api/requests/ - API client (auto-generated from OpenAPI)
  • api/queries/ - TanStack Query hooks
  • hooks/ - Custom business logic hooks
  • components/ - UI presentation layer

TanStack Query Benefits:

  • Automatic caching and refetching
  • Loading and error states
  • Optimistic updates
  • Request deduplication

🛠️ Development Tools​

Built-in tooling:

  • Next.js with Turbopack: Ultra-fast dev server and builds
  • TypeScript: Full type safety across the application
  • ESLint: Code quality and linting
  • TailwindCSS: Utility-first styling

Key commands:

npm run dev          # Start Next.js dev server
npm run build        # Production build
npm run start        # Start production server
npm run codegen      # Generate API client from backend OpenAPI
npm run typecheck    # TypeScript type checking
npm run lint         # ESLint checking
npm run lint:fix     # Fix ESLint issues

🎯 Code Organization Principles​

Feature-First Organization​

components/features/
├── chat/                    # All chat-related components
│   ├── ChatMessage.tsx     # Individual message display
│   ├── ChatInput.tsx       # Message input form
│   └── ChatHistory.tsx     # Message list
└── tasks/                   # All task-related components
    ├── TaskItem.tsx        # Single task display
    ├── TaskForm.tsx        # Task creation form
    └── TaskList.tsx        # Task list container

Import Hierarchy​

// ✅ Good - Clear dependency direction
app/**/page.tsx imports → components/features/
components/features/ imports → components/ui/
hooks/ imports → api/queries/
api/queries/ imports → api/requests/

// ❌ Avoid - Circular dependencies
features ↔ features (use shared hooks instead)
ui → features (ui should be generic)
app → components (pages should use features, not import components directly)

File Naming Conventions​

PascalCase.tsx     # React components
camelCase.ts       # Hooks, utilities, stores
kebab-case.css     # Style files
lowercase/         # Directories

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