# 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