Skip to content

App Package

Overview

The @delta/app package is a Next.js-based web application that serves as the main user interface for the Delta platform. It provides a modern, responsive web interface with authentication, real-time features, and integration with backend services.

Technology Stack

  • Framework: Next.js 15+ with App Router
  • Styling: Tailwind CSS with custom components
  • UI Components: Custom component library with Storybook documentation
  • Authentication: Supabase Auth integration
  • State Management: React Context API
  • Testing: Jest + React Testing Library + Vitest
  • Type Safety: TypeScript

Key Features

Authentication

  • Location: src/contexts/AuthContext.tsx
  • Features:
  • Supabase-based authentication
  • Protected routes
  • User session management
  • Role-based access control

API Integration

  • Location: app/api/
  • Endpoints:
  • /api/log-error - Error logging endpoint
  • /api/process-with-aihub - AI Hub integration
  • /api/sana - Sana service integration
  • /api/update-item-status - Item status management

Logging

  • Client-side: src/lib/clientLogger.ts
  • Server-side: src/lib/serverLogger.ts
  • Features:
  • Environment-aware logging
  • Integration with @delta/common logger
  • Error tracking and reporting

UI Components

  • Location: src/components/
  • Documentation: Storybook stories in src/stories/
  • Features:
  • Reusable component library
  • Consistent design system
  • Accessibility compliance

Development

Local Development

# Install dependencies
npm install

# Start development server
npm run dev

# Open browser to http://localhost:3000

Environment Setup

Copy .env.local.example to .env.local and configure:

  • Supabase credentials
  • API endpoints
  • Feature flags

Storybook

# Start Storybook
npm run storybook

# Build Storybook
npm run build-storybook

Testing

The app package includes comprehensive testing infrastructure:

Unit Tests (Jest + React Testing Library)

# Run Jest tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run tests for CI/CD
npm run test:ci

Component Testing (Vitest)

# Run Vitest tests
npm run test:vitest

End-to-End Testing (Playwright)

# Run E2E tests
npm run e2e

# Run E2E tests in UI mode (recommended for development)
npm run e2e:ui

# Run E2E tests with visible browser
npm run e2e:headed

# Debug E2E tests
npm run e2e:debug

# Run E2E tests with Allure reporting
npm run e2e:test-allure

# View E2E test report
npm run e2e:report

Test Technologies

  • Unit Testing: Jest, React Testing Library
  • Component Testing: Vitest
  • E2E Testing: Playwright
  • E2E Test Reporting: Allure Reports

Test Coverage

  • Statements: 80%
  • Branches: 75%
  • Functions: 80%
  • Lines: 80%

Current Test Status

  • ✅ Button Component: 24/24 tests passing
  • ✅ Utils Functions: 17/17 tests passing
  • ⚠️ AuthContext: Needs mock refinement
  • ⚠️ API Routes: Needs environment setup

Build and Deployment

Production Build

# Build for production
npm run build

# Start production server
npm start

Static Export

# Export static site
npm run export

Configuration Files

  • next.config.mjs - Next.js configuration
  • tailwind.config.js - Tailwind CSS configuration
  • postcss.config.mjs - PostCSS configuration
  • components.json - UI components configuration
  • jest.config.js - Jest testing configuration
  • vitest.config.ts - Vitest configuration

Dependencies

Runtime Dependencies

  • Next.js, React, Tailwind CSS
  • Supabase client for authentication and database
  • Alova for HTTP requests (lightweight request library with caching)
  • Radix UI for accessible components
  • Class Variance Authority for component variants

Development Dependencies

  • TypeScript, ESLint, Prettier
  • Jest, React Testing Library, Vitest
  • Storybook for component documentation
  • MSW for API mocking

Internal Dependencies

  • @delta/common - Shared utilities and logging

Integration Points

  • Database: Supabase for database and authentication
  • AI Services: Integration with AI Hub for processing
  • Sana: Integration with Sana service
  • Logging: Centralized logging through common package

Deployment

The app is configured for deployment on Vercel with:

  • Automatic deployments from Git
  • Environment variable management
  • Preview deployments for pull requests
  • Production optimizations

File Structure

src/
├── components/          # Reusable UI components
│   └── ui/             # Base UI components
├── contexts/           # React contexts
├── lib/               # Utility libraries
├── pages/             # Next.js pages
├── stories/           # Storybook stories
└── styles/            # Global styles

app/
├── api/               # API routes
└── ...                # App router pages

Best Practices

  1. Co-located Tests: Keep tests next to the code they test
  2. Component Documentation: Use Storybook for component documentation
  3. Type Safety: Leverage TypeScript for type safety
  4. Accessibility: Follow accessibility best practices
  5. Performance: Optimize for Core Web Vitals