Skip to content

Delta Packages Documentation

This directory contains comprehensive documentation for all packages in the Delta monorepo. Each package has been documented with its purpose, architecture, development setup, testing, and deployment information.

Package Overview

Core Packages

@delta/common

Shared utilities and foundation

  • Centralized logging with Winston and Loki integration
  • Environment detection utilities
  • Shared enums and type definitions
  • Used by all other packages for consistent functionality

@delta/app

Next.js web application

  • Modern React-based user interface
  • Supabase authentication integration
  • Comprehensive testing with Jest and Vitest
  • Storybook component documentation
  • Tailwind CSS styling

@delta/aiHub

AI processing service

  • Node.js service for AI operations
  • Express.js HTTP server
  • AWS SQS integration for message queuing
  • Docker containerization support
  • Scalable AI workload management

Sana

Sana service integration

  • API client for Sana services
  • Data synchronization and transformation
  • Error handling and retry mechanisms
  • TypeScript library package

Infrastructure Packages

Database (Supabase)

Database services

  • PostgreSQL database with Supabase
  • Database migrations and schema management
  • Edge functions with Deno runtime
  • Authentication and authorization
  • Real-time subscriptions

Lambda Functions

AWS serverless functions

  • AI Hub SQS Processor for message handling
  • API Gateway Authorizer for authentication
  • Optimized builds with esbuild
  • AWS SDK integrations

Architecture Overview

┌─────────────────┐    ┌─────────────────┐
│   App           │    │    AI Hub       │
│   (Next.js)     │◄──►│   (Node.js)     │
└─────────────────┘    └─────────────────┘
         │                       │
         ▼                       ▼
┌─────────────────┐    ┌─────────────────┐
│    Database     │    │ Lambda Functions│
│   (Supabase)    │    │     (AWS)       │
└─────────────────┘    └─────────────────┘

Package Dependencies

Internal Dependencies

  • App → Common
  • AI Hub → Common
  • Lambda Functions → Common
  • Database → Standalone (Supabase)

External Dependencies

  • Database: PostgreSQL via Supabase
  • Cloud Services: AWS (SQS, ECS, Lambda)
  • Authentication: Supabase Auth
  • Logging: Winston with Loki
  • Testing: Jest, React Testing Library, Vitest

Development Workflow

Getting Started

  1. Clone Repository: Get the Delta monorepo
  2. Install Dependencies: Run yarn install at root
  3. Environment Setup: Configure .env.local files
  4. Start Services: Use development scripts

Package Development

  1. Common Changes: Update shared utilities first
  2. Build Dependencies: Ensure dependent packages rebuild
  3. Testing: Run tests for affected packages
  4. Integration: Test package interactions

Testing Strategy

  • Unit Tests: Each package has comprehensive unit tests
  • Integration Tests: Cross-package functionality testing
  • E2E Tests: Full application workflow testing
  • Type Safety: TypeScript for compile-time error checking

Deployment

Development Environment

  • Local development with hot reloading
  • Docker containers for services
  • Local Supabase instance
  • Mock external services

Staging Environment

  • Deployed packages with staging configurations
  • Integration with staging external services
  • End-to-end testing environment
  • Performance monitoring

Production Environment

  • Optimized builds and deployments
  • Production database and services
  • Monitoring and alerting
  • Backup and disaster recovery

Documentation Standards

Each package documentation includes:

Structure

  • Overview: Purpose and high-level description
  • Technology Stack: Frameworks and tools used
  • Key Components: Main modules and features
  • Development: Local setup and workflow
  • Testing: Test strategy and execution
  • Build & Deployment: Production preparation
  • Configuration: Environment and settings
  • Dependencies: Internal and external dependencies
  • Integration Points: How it connects to other packages

Code Examples

  • Configuration snippets
  • Usage examples
  • Common patterns
  • Best practices

Troubleshooting

  • Common issues and solutions
  • Debug procedures
  • Performance optimization
  • Security considerations

Migration from Local READMEs

This centralized documentation replaces the individual README files in each package directory. The benefits include:

Centralization

  • Single location for all package documentation
  • Consistent documentation structure
  • Cross-package relationship visibility
  • Easier maintenance and updates

Comprehensive Coverage

  • More detailed information than local READMEs
  • Architecture and integration details
  • Development and deployment workflows
  • Testing and troubleshooting guides

Discoverability

  • All package information in one place
  • Clear navigation between packages
  • Overview of entire system architecture
  • Dependency relationships

Contributing

When adding new packages or updating existing ones:

  1. Create Documentation: Add comprehensive package documentation
  2. Update Overview: Update this README with new package information
  3. Architecture Diagrams: Update system architecture if needed
  4. Dependencies: Document new internal/external dependencies
  5. Integration: Explain how the package fits into the overall system

Next Steps

After reviewing this documentation:

  1. Remove Local READMEs: Delete README files from individual package directories
  2. Update References: Update any documentation links to point to centralized docs
  3. Team Training: Ensure team members know about the new documentation structure
  4. Maintenance: Keep documentation updated as packages evolve