buster/web/README.md

# Buster Web Application

## Project Overview
This is a modern web application built with Next.js 14+, utilizing the App Router architecture. The application is structured to provide a scalable, maintainable, and performant user experience.

## Project Architecture

### Directory Structure
```
src/
├── api/
│   ├── buster_rest/     # REST API integrations
│   ├── buster_socket/   # WebSocket implementations
│   └── asset_interfaces/# TypeScript interfaces for API responses
├── app/                # Next.js App Router directory
│   └── app/           # Main application routes
│       ├── _components/     # Global components that are route specific and shared across pages
│       ├── _controllers/    # Business logic controllers
│       ├── _layouts/        # Shared layout components
│       ├── (chat_experience)/ # Every page that will require a "chat" experience.
│       ├── collections/     # Collections feature
│       ├── dashboards/      # Dashboard views
│       ├── datasets/        # Dataset management
│       ├── logs/           # Metrics (admin view)
│       ├── metrics/        # Metrics generated by the user
│       ├── new-user/       # New user onboarding
│       ├── settings/       # User settings
│       └── terms/          # Terms that were defined for all the datasets
├── components/          # Reusable React components
├── config/             # Application configuration files
├── context/            # React Context providers
├── hooks/              # Custom React hooks
├── middleware/         # Request/response middleware
├── routes/             # Application routing logic
└── utils/             # Utility functions and helpers
```

## Technical Stack
- **Framework**: Next.js 14+ with App Router
- **Language**: TypeScript
- **State Management**: React Context
- **API Integration**: REST and WebSocket
- **Styling**: [Your styling solution]

## Getting Started

### Prerequisites
- Node.js 18.x or higher
- npm or yarn package manager

### Development Setup
1. Install dependencies:
```bash
npm install
# or
yarn install
```

3. Run the development server:
```bash
npm run dev
# or
yarn dev
```

The application will be available at [http://localhost:3000](http://localhost:3000).

## Key Features
- Real-time communication via WebSocket
- REST API integration
- Centralized state management using Context
- Component-based architecture
- Type-safe development with TypeScript

## Project Structure Details

### API Layer (`src/api/`)
- `buster_rest/`: REST API implementations for various features
- `buster_socket/`: WebSocket implementations for real-time features
- `asset_interfaces/`: TypeScript interfaces defining API response structures

### Components (`src/components/`)
Reusable React components organized by feature or functionality.

### Config (`src/config/`)
Configuration files and environment-specific settings:
- Environment variables management
- Feature flags
- API endpoints configuration
- Application-wide constants

### Context (`src/context/`)
Global state management using React Context, including:
- Metrics tracking
- Application-wide state management
- Individual metric providers

### Hooks (`src/hooks/`)
Custom React hooks that encapsulate reusable stateful logic:
- Data fetching hooks
- State management hooks
- Utility hooks for common functionality
- Feature-specific hooks

### Middleware (`src/middleware/`)
Request/response middleware handlers:
- Authentication middleware
- Request validation
- Response transformation
- Error handling middleware

### Routes (`src/routes/`)
Application routing and page structure:
- Route definitions
- Page components
- Route-specific logic
- Navigation configuration

### Utils (`src/utils/`)
Helper functions and utilities used across the application.

### App Router Architecture (`src/app/`)
The application uses Next.js 14+ App Router, following a feature-first organization within the `app` directory:

#### Core Structure
- `_components/`: Route-specific shared components that are used across multiple pages within the app
- `_controllers/`: Business logic controllers that handle data flow and state management
- `_layouts/`: Shared layout components for consistent page structure

#### Feature Organization
- `(chat_experience)/`: Grouped chat-related features (using route groups)
  - Isolated chat functionality
  - Real-time messaging components
  - Chat-specific layouts

#### Main Features
- `collections/`: Management and display of user collections
- `dashboards/`: Data visualization and analytics dashboards
- `datasets/`: Dataset creation, management, and analysis tools
- `logs/`: System and user activity logging interface
- `metrics/`: Performance and usage metrics visualization
- `new-user/`: User onboarding flow and initial setup
- `settings/`: User preferences and application configuration
- `terms/`: Legal documentation and user agreements

#### Layout Structure
- `layout.tsx`: Root layout component providing common UI elements
- `layoutClient.tsx`: Client-side layout components for dynamic features
- `page.tsx`: Main entry point for each route

This organization follows Next.js best practices for:
- Route Groups and Layouts
- Server and Client Components
- Colocation of Related Features
- Parallel Routes and Intercepted Routes

## Development Guidelines

### Code Style
- Use functional components with hooks
- Follow TypeScript best practices
- Maintain consistent naming conventions
- Write clean, self-documenting code

### Component Development
- Create reusable components
- Implement proper prop typing
- Follow the single responsibility principle

### State Management
- Use React Context for global state
- Implement proper error boundaries
- Handle loading states appropriately

## Deployment
The application can be deployed using various platforms:

1. **Vercel** (Recommended):
   - Automatic deployments with Git integration
   - Built-in performance optimization
   - Zero-configuration setup

2. **Manual Deployment**:
   - Build the application:
     ```bash
     npm run build
     # or
     yarn build
     ```
   - Start the production server:
     ```bash
     npm start
     # or
     yarn start
     ```