adding freight web and holding
This commit is contained in:
@@ -1,249 +1,249 @@
|
||||
# Technology Stack - Star Kitten
|
||||
|
||||
## Core Technologies
|
||||
|
||||
### Runtime & Package Management
|
||||
|
||||
- **Bun** - JavaScript runtime and package manager
|
||||
- Fast package installation and script execution
|
||||
- Native TypeScript support
|
||||
- Built-in test runner (`bun test`)
|
||||
- WebAPI compatibility for modern web standards
|
||||
|
||||
### Language & Type System
|
||||
|
||||
- **TypeScript** - Primary development language
|
||||
- Strict type checking enabled across all packages
|
||||
- Comprehensive type definitions for EVE Online data structures
|
||||
- Interface-driven development for API integrations
|
||||
- Global type declarations for shared client instances
|
||||
|
||||
### Build System
|
||||
|
||||
- **Workspace Architecture** - Bun workspaces for monorepo management
|
||||
- Four core packages: `@star-kitten/discord`, `@star-kitten/eve`, `@star-kitten/util`, plus applications
|
||||
- Cross-package dependencies managed through workspace references
|
||||
- Unified build commands across all packages (`bun build`, `bun dev`, `bun test`)
|
||||
- **tsdown** - TypeScript bundler for package builds
|
||||
- Zero-config TypeScript compilation
|
||||
- Watch mode support for development
|
||||
- Declaration file generation
|
||||
|
||||
## Discord Integration
|
||||
|
||||
### Discord Framework
|
||||
|
||||
- **Dysnomia** - Discord API library
|
||||
- Modern JavaScript Discord library with full TypeScript support
|
||||
- Gateway intents configuration for minimal resource usage
|
||||
- Built-in interaction handling (slash commands, modals, components)
|
||||
- Event-driven architecture for command processing
|
||||
|
||||
### Command Architecture
|
||||
|
||||
- **Auto-discovery Pattern** - Commands automatically registered via file system scanning
|
||||
- Glob patterns (`**/*.command.{js,ts}`) for command file detection
|
||||
- Convention-based naming and structure
|
||||
- Global client registration with event listeners
|
||||
- **Internationalization** - Full i18n support
|
||||
- Command names and descriptions localized across multiple languages
|
||||
- Structured translation files for consistent localization
|
||||
|
||||
## Database & Data Management
|
||||
|
||||
### Database Layer
|
||||
|
||||
- **SQLite** - Local database storage
|
||||
- Single-file database for simple deployment
|
||||
- ACID compliance for data integrity
|
||||
- Excellent performance for read-heavy workloads
|
||||
- **Drizzle ORM** - Type-safe database access
|
||||
- Schema-first approach with TypeScript definitions
|
||||
- Automatic migration generation via Drizzle Kit
|
||||
- Relationship mapping and query builder
|
||||
- Active Record pattern implementation in model helpers
|
||||
|
||||
### Data Processing
|
||||
|
||||
- **Streaming JSON Processing** - Memory-efficient handling of large datasets
|
||||
- `stream-json` library for parsing large EVE reference data files
|
||||
- Query-based filtering during stream processing
|
||||
- In-memory caching with TTL for frequently accessed data
|
||||
- **Reference Data Management**
|
||||
- External data sources (everef.net, hoboleaks)
|
||||
- Automated download and extraction scripts
|
||||
- Static export processes for optimized data formats
|
||||
|
||||
## Web Framework
|
||||
|
||||
### Frontend Framework
|
||||
|
||||
- **Brisa** - Server-side rendering framework
|
||||
- Modern SSR with progressive enhancement
|
||||
- Component-based architecture
|
||||
- Built-in suspense support for async data loading
|
||||
- TypeScript-first development experience
|
||||
|
||||
### Styling & UI
|
||||
|
||||
- **Tailwind CSS** - Utility-first CSS framework
|
||||
- Responsive design system
|
||||
- Component-level styling
|
||||
- **DaisyUI** - Tailwind CSS component library
|
||||
- Pre-built UI components (stats, progress bars, modals)
|
||||
- Consistent design language across web interface
|
||||
|
||||
### Authentication & Middleware
|
||||
|
||||
- **EVE SSO Integration** - OAuth2 flow implementation
|
||||
- Complete authentication middleware stack
|
||||
- Token management with automatic refresh
|
||||
- Scope validation and permission handling
|
||||
- **Cookie Management** - Custom utilities for session handling
|
||||
- Secure cookie implementation
|
||||
- State management for OAuth flows
|
||||
|
||||
## External API Integrations
|
||||
|
||||
### EVE Online APIs
|
||||
|
||||
- **ESI (EVE Swagger Interface)** - Official EVE Online API
|
||||
- Complete OAuth2 flow with scope management
|
||||
- Character, corporation, and alliance data access
|
||||
- Market data, skill queues, wallet information
|
||||
- Automatic token refresh with scope preservation
|
||||
- **JWT Token Validation** - Secure token handling
|
||||
- Public key verification against EVE's JWKS endpoint
|
||||
- Token scope extraction and validation
|
||||
- Character ID resolution from JWT payloads
|
||||
|
||||
### Third-Party APIs
|
||||
|
||||
- **Janice API** - Market appraisal service
|
||||
- Price checking and market analysis
|
||||
- Bulk item appraisal functionality
|
||||
- Caching layer for improved performance
|
||||
- **EveTycoon API** - Market data integration
|
||||
- Historical price data
|
||||
- Market trend analysis
|
||||
|
||||
## Development Tools & Practices
|
||||
|
||||
### Code Quality
|
||||
|
||||
- **Prettier** - Code formatting
|
||||
- Consistent formatting across all packages
|
||||
- Integration with VS Code for format-on-save
|
||||
- Shared configuration files (`.prettierrc.yaml`)
|
||||
- **ESLint** - Code linting (implied by VS Code settings)
|
||||
- TypeScript-aware linting rules
|
||||
- Automatic fixing on save
|
||||
|
||||
### Testing Framework
|
||||
|
||||
- **Bun Test** - Native test runner
|
||||
- Fast test execution with TypeScript support
|
||||
- Coverage reporting capabilities
|
||||
- Target: 80%+ test coverage across major functionality
|
||||
|
||||
### Development Environment
|
||||
|
||||
- **VS Code Configuration**
|
||||
- Consistent editor settings across team
|
||||
- Format on save enabled
|
||||
- Trailing whitespace removal
|
||||
- Final newline insertion
|
||||
- **Environment Management**
|
||||
- dotenvx for environment variable management
|
||||
- Separate configurations for development and production
|
||||
- Secure key management for API credentials
|
||||
|
||||
## Utility Libraries
|
||||
|
||||
### Scheduling & Background Jobs
|
||||
|
||||
- **Cron Parser** - Schedule management
|
||||
- Cron expression parsing and validation
|
||||
- Job scheduling with repeat patterns
|
||||
- **Custom Queue System** - Background job processing
|
||||
- SQLite-based job queue
|
||||
- Worker thread implementation
|
||||
- Email notifications and other background tasks
|
||||
|
||||
### Text & Data Processing
|
||||
|
||||
- **Date Utilities** - Time manipulation
|
||||
- date-fns for date calculations
|
||||
- EVE time conversion utilities
|
||||
- **Logging** - Structured application logs
|
||||
- Winston logging framework
|
||||
- Configurable log levels and outputs
|
||||
- **Text Processing** - Formatting and conversion
|
||||
- Number formatting (K, M, B suffixes)
|
||||
- EVE markup to Discord markdown conversion
|
||||
- Text truncation and cleaning utilities
|
||||
|
||||
## Deployment & Configuration
|
||||
|
||||
### Environment Configuration
|
||||
|
||||
- **Multi-Environment Support**
|
||||
- Development, production environment files
|
||||
- Secure API key management
|
||||
- Database path configuration
|
||||
- **Docker Ready** - Containerization support
|
||||
- Bun-based container builds
|
||||
- SQLite database volume mounting
|
||||
|
||||
### Database Management
|
||||
|
||||
- **Migration System** - Schema version control
|
||||
- Drizzle Kit migration generation
|
||||
- Automated migration execution
|
||||
- Schema evolution tracking
|
||||
|
||||
## Architecture Patterns
|
||||
|
||||
### Package Organization
|
||||
|
||||
- **Modular Monorepo** - Clear separation of concerns
|
||||
- Core packages for reusable functionality
|
||||
- Application packages for specific implementations
|
||||
- Shared utilities across packages
|
||||
- **Export Patterns** - Structured package APIs
|
||||
- Namespace exports for logical grouping
|
||||
- Direct exports for commonly used functions
|
||||
- Type-only exports where appropriate
|
||||
|
||||
### Error Handling
|
||||
|
||||
- **Consistent Error Patterns** - Standardized error handling
|
||||
- API error wrapping and propagation
|
||||
- Graceful degradation for external service failures
|
||||
- Comprehensive error logging
|
||||
|
||||
### Performance Optimizations
|
||||
|
||||
- **Caching Strategy** - Multi-level caching
|
||||
- In-memory caching for frequently accessed data
|
||||
- Database-level caching for computed results
|
||||
- HTTP response caching for external APIs
|
||||
- **Streaming Processing** - Memory-efficient data handling
|
||||
- Large file processing without memory overflow
|
||||
- Real-time data updates through streaming APIs
|
||||
|
||||
## Future Technology Considerations
|
||||
|
||||
### Migration Plans
|
||||
|
||||
- **Web Framework Migration** - Planned transition from Brisa to Elysia + Ripple SPA
|
||||
- Backend: Elysia for high-performance HTTP server
|
||||
- Frontend: Ripple SPA for modern client-side architecture
|
||||
- Gradual migration strategy maintaining backward compatibility
|
||||
|
||||
### Expansion Capabilities
|
||||
|
||||
- **Multi-Game Support** - Architecture designed for game expansion
|
||||
- Pluggable game integration modules
|
||||
- Shared utilities across different game APIs
|
||||
- Common authentication and data patterns
|
||||
# Technology Stack - Star Kitten
|
||||
|
||||
## Core Technologies
|
||||
|
||||
### Runtime & Package Management
|
||||
|
||||
- **Bun** - JavaScript runtime and package manager
|
||||
- Fast package installation and script execution
|
||||
- Native TypeScript support
|
||||
- Built-in test runner (`bun test`)
|
||||
- WebAPI compatibility for modern web standards
|
||||
|
||||
### Language & Type System
|
||||
|
||||
- **TypeScript** - Primary development language
|
||||
- Strict type checking enabled across all packages
|
||||
- Comprehensive type definitions for EVE Online data structures
|
||||
- Interface-driven development for API integrations
|
||||
- Global type declarations for shared client instances
|
||||
|
||||
### Build System
|
||||
|
||||
- **Workspace Architecture** - Bun workspaces for monorepo management
|
||||
- Four core packages: `@star-kitten/discord`, `@star-kitten/eve`, `@star-kitten/util`, plus applications
|
||||
- Cross-package dependencies managed through workspace references
|
||||
- Unified build commands across all packages (`bun build`, `bun dev`, `bun test`)
|
||||
- **tsdown** - TypeScript bundler for package builds
|
||||
- Zero-config TypeScript compilation
|
||||
- Watch mode support for development
|
||||
- Declaration file generation
|
||||
|
||||
## Discord Integration
|
||||
|
||||
### Discord Framework
|
||||
|
||||
- **Dysnomia** - Discord API library
|
||||
- Modern JavaScript Discord library with full TypeScript support
|
||||
- Gateway intents configuration for minimal resource usage
|
||||
- Built-in interaction handling (slash commands, modals, components)
|
||||
- Event-driven architecture for command processing
|
||||
|
||||
### Command Architecture
|
||||
|
||||
- **Auto-discovery Pattern** - Commands automatically registered via file system scanning
|
||||
- Glob patterns (`**/*.command.{js,ts}`) for command file detection
|
||||
- Convention-based naming and structure
|
||||
- Global client registration with event listeners
|
||||
- **Internationalization** - Full i18n support
|
||||
- Command names and descriptions localized across multiple languages
|
||||
- Structured translation files for consistent localization
|
||||
|
||||
## Database & Data Management
|
||||
|
||||
### Database Layer
|
||||
|
||||
- **SQLite** - Local database storage
|
||||
- Single-file database for simple deployment
|
||||
- ACID compliance for data integrity
|
||||
- Excellent performance for read-heavy workloads
|
||||
- **Drizzle ORM** - Type-safe database access
|
||||
- Schema-first approach with TypeScript definitions
|
||||
- Automatic migration generation via Drizzle Kit
|
||||
- Relationship mapping and query builder
|
||||
- Active Record pattern implementation in model helpers
|
||||
|
||||
### Data Processing
|
||||
|
||||
- **Streaming JSON Processing** - Memory-efficient handling of large datasets
|
||||
- `stream-json` library for parsing large EVE reference data files
|
||||
- Query-based filtering during stream processing
|
||||
- In-memory caching with TTL for frequently accessed data
|
||||
- **Reference Data Management**
|
||||
- External data sources (everef.net, hoboleaks)
|
||||
- Automated download and extraction scripts
|
||||
- Static export processes for optimized data formats
|
||||
|
||||
## Web Framework
|
||||
|
||||
### Frontend Framework
|
||||
|
||||
- **Brisa** - Server-side rendering framework
|
||||
- Modern SSR with progressive enhancement
|
||||
- Component-based architecture
|
||||
- Built-in suspense support for async data loading
|
||||
- TypeScript-first development experience
|
||||
|
||||
### Styling & UI
|
||||
|
||||
- **Tailwind CSS** - Utility-first CSS framework
|
||||
- Responsive design system
|
||||
- Component-level styling
|
||||
- **DaisyUI** - Tailwind CSS component library
|
||||
- Pre-built UI components (stats, progress bars, modals)
|
||||
- Consistent design language across web interface
|
||||
|
||||
### Authentication & Middleware
|
||||
|
||||
- **EVE SSO Integration** - OAuth2 flow implementation
|
||||
- Complete authentication middleware stack
|
||||
- Token management with automatic refresh
|
||||
- Scope validation and permission handling
|
||||
- **Cookie Management** - Custom utilities for session handling
|
||||
- Secure cookie implementation
|
||||
- State management for OAuth flows
|
||||
|
||||
## External API Integrations
|
||||
|
||||
### EVE Online APIs
|
||||
|
||||
- **ESI (EVE Swagger Interface)** - Official EVE Online API
|
||||
- Complete OAuth2 flow with scope management
|
||||
- Character, corporation, and alliance data access
|
||||
- Market data, skill queues, wallet information
|
||||
- Automatic token refresh with scope preservation
|
||||
- **JWT Token Validation** - Secure token handling
|
||||
- Public key verification against EVE's JWKS endpoint
|
||||
- Token scope extraction and validation
|
||||
- Character ID resolution from JWT payloads
|
||||
|
||||
### Third-Party APIs
|
||||
|
||||
- **Janice API** - Market appraisal service
|
||||
- Price checking and market analysis
|
||||
- Bulk item appraisal functionality
|
||||
- Caching layer for improved performance
|
||||
- **EveTycoon API** - Market data integration
|
||||
- Historical price data
|
||||
- Market trend analysis
|
||||
|
||||
## Development Tools & Practices
|
||||
|
||||
### Code Quality
|
||||
|
||||
- **Prettier** - Code formatting
|
||||
- Consistent formatting across all packages
|
||||
- Integration with VS Code for format-on-save
|
||||
- Shared configuration files (`.prettierrc.yaml`)
|
||||
- **ESLint** - Code linting (implied by VS Code settings)
|
||||
- TypeScript-aware linting rules
|
||||
- Automatic fixing on save
|
||||
|
||||
### Testing Framework
|
||||
|
||||
- **Bun Test** - Native test runner
|
||||
- Fast test execution with TypeScript support
|
||||
- Coverage reporting capabilities
|
||||
- Target: 80%+ test coverage across major functionality
|
||||
|
||||
### Development Environment
|
||||
|
||||
- **VS Code Configuration**
|
||||
- Consistent editor settings across team
|
||||
- Format on save enabled
|
||||
- Trailing whitespace removal
|
||||
- Final newline insertion
|
||||
- **Environment Management**
|
||||
- dotenvx for environment variable management
|
||||
- Separate configurations for development and production
|
||||
- Secure key management for API credentials
|
||||
|
||||
## Utility Libraries
|
||||
|
||||
### Scheduling & Background Jobs
|
||||
|
||||
- **Cron Parser** - Schedule management
|
||||
- Cron expression parsing and validation
|
||||
- Job scheduling with repeat patterns
|
||||
- **Custom Queue System** - Background job processing
|
||||
- SQLite-based job queue
|
||||
- Worker thread implementation
|
||||
- Email notifications and other background tasks
|
||||
|
||||
### Text & Data Processing
|
||||
|
||||
- **Date Utilities** - Time manipulation
|
||||
- date-fns for date calculations
|
||||
- EVE time conversion utilities
|
||||
- **Logging** - Structured application logs
|
||||
- Winston logging framework
|
||||
- Configurable log levels and outputs
|
||||
- **Text Processing** - Formatting and conversion
|
||||
- Number formatting (K, M, B suffixes)
|
||||
- EVE markup to Discord markdown conversion
|
||||
- Text truncation and cleaning utilities
|
||||
|
||||
## Deployment & Configuration
|
||||
|
||||
### Environment Configuration
|
||||
|
||||
- **Multi-Environment Support**
|
||||
- Development, production environment files
|
||||
- Secure API key management
|
||||
- Database path configuration
|
||||
- **Docker Ready** - Containerization support
|
||||
- Bun-based container builds
|
||||
- SQLite database volume mounting
|
||||
|
||||
### Database Management
|
||||
|
||||
- **Migration System** - Schema version control
|
||||
- Drizzle Kit migration generation
|
||||
- Automated migration execution
|
||||
- Schema evolution tracking
|
||||
|
||||
## Architecture Patterns
|
||||
|
||||
### Package Organization
|
||||
|
||||
- **Modular Monorepo** - Clear separation of concerns
|
||||
- Core packages for reusable functionality
|
||||
- Application packages for specific implementations
|
||||
- Shared utilities across packages
|
||||
- **Export Patterns** - Structured package APIs
|
||||
- Namespace exports for logical grouping
|
||||
- Direct exports for commonly used functions
|
||||
- Type-only exports where appropriate
|
||||
|
||||
### Error Handling
|
||||
|
||||
- **Consistent Error Patterns** - Standardized error handling
|
||||
- API error wrapping and propagation
|
||||
- Graceful degradation for external service failures
|
||||
- Comprehensive error logging
|
||||
|
||||
### Performance Optimizations
|
||||
|
||||
- **Caching Strategy** - Multi-level caching
|
||||
- In-memory caching for frequently accessed data
|
||||
- Database-level caching for computed results
|
||||
- HTTP response caching for external APIs
|
||||
- **Streaming Processing** - Memory-efficient data handling
|
||||
- Large file processing without memory overflow
|
||||
- Real-time data updates through streaming APIs
|
||||
|
||||
## Future Technology Considerations
|
||||
|
||||
### Migration Plans
|
||||
|
||||
- **Web Framework Migration** - Planned transition from Brisa to Elysia + Ripple SPA
|
||||
- Backend: Elysia for high-performance HTTP server
|
||||
- Frontend: Ripple SPA for modern client-side architecture
|
||||
- Gradual migration strategy maintaining backward compatibility
|
||||
|
||||
### Expansion Capabilities
|
||||
|
||||
- **Multi-Game Support** - Architecture designed for game expansion
|
||||
- Pluggable game integration modules
|
||||
- Shared utilities across different game APIs
|
||||
- Common authentication and data patterns
|
||||
|
||||
Reference in New Issue
Block a user