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:

npm install
# or
yarn install

3. Run the development server:

npm run dev
# or
yarn dev

The application will be available at 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:

     npm run build
     # or
     yarn build
     

   • Start the production server:

     npm start
     # or
     yarn start