star-kitten/.kilocode/rules/memory-bank/tech.md

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