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

Architecture Overview - Star Kitten

System Architecture

Star Kitten follows a modular monorepo architecture with four main packages and two applications:

graph TB
    subgraph "Applications"
        EB[eve-bot<br/>Discord Bot]
        EW[eve-web<br/>Brisa Web App]
    end

    subgraph "Core Packages"
        D[@star-kitten/discord<br/>Discord Framework]
        E[@star-kitten/eve<br/>EVE Online Integration]
        U[@star-kitten/util<br/>Shared Utilities]
    end

    subgraph "External Services"
        DS[Discord API]
        ESI[EVE ESI API]
        JA[Janice API]
        ET[EveTycoon API]
    end

    subgraph "Data Layer"
        DB[(SQLite Database)]
        RD[(Reference Data<br/>JSON Files)]
    end

    EB --> D
    EB --> E
    EW --> E
    EW --> U
    D --> DS
    E --> ESI
    E --> JA
    E --> ET
    E --> DB
    E --> RD
    U --> DB

Source Code Paths

Core Packages

@star-kitten/discord

• Entry Point: packages/discord/src/index.ts
• Command System: packages/discord/src/commands/
  • import-commands.ts - Auto-discovery of command files
  • handle-commands.ts - Command execution handler
• Localization: packages/discord/src/locales.ts

@star-kitten/eve

• Entry Point: packages/eve/src/index.ts
• Database Layer: packages/eve/src/db/
  • schema.ts - Drizzle ORM schema definitions
  • index.ts - Database connection and exports
  • models/ - Character and user model helpers
• ESI Integration: packages/eve/src/esi/
  • auth.ts - EVE SSO authentication flow
  • scopes.ts - ESI scope definitions and token validation
  • character.ts - Character API endpoints
  • fetch.ts - ESI API client wrapper
• Data Models: packages/eve/src/models/
  • type.ts - EVE item type definitions and utilities
  • skill.ts - Skill-related models
• Third-party APIs: packages/eve/src/third-party/
  • janice.ts - Market appraisal integration
  • evetycoon.ts - Market data integration
• Utilities: packages/eve/src/utils/
  • markdown.ts - EVE markup to Discord formatting

@star-kitten/util

• Entry Point: packages/util/src/ (no index.ts, exports individual modules)
• Core Utilities:
  • text.ts - Text processing and formatting
  • jsonQuery.ts - Streaming JSON querying for large files
  • time.ts - Time utilities
  • logger.ts - Logging utilities
• Scheduler System: packages/util/src/scheduler/
  • scheduler.service.ts - Job scheduling service
  • queue.ts - Job queue implementation
  • workers/ - Background worker implementations

Applications

eve-bot

• Entry Point: packages/eve-bot/src/main.ts
• Commands: packages/eve-bot/src/commands/
  • appraise.command.ts - Market appraisal command
• Types: packages/eve-bot/src/types/global.d.ts

eve-web

• Entry Point: packages/eve-web/src/pages/index.tsx
• Middleware: packages/eve-web/src/middleware.ts - EVE SSO integration
• Components: packages/eve-web/src/components/stats/
  • skill-queue.tsx - Real-time skill training display
  • wallet.tsx - Wallet balance and changes
• API Routes: packages/eve-web/src/api/auth/ - Authentication endpoints
• Utilities: packages/eve-web/src/utils/cookies.ts

Key Technical Decisions

Command System Architecture

• Auto-discovery: Commands are automatically discovered using glob patterns (**/*.command.{js,ts})
• Convention-based: Each command exports a default Discord command definition
• Event-driven: Commands handle their own interaction events using global event listeners
• Localized: Full internationalization support with description translations

Database Architecture

• ORM: Drizzle ORM with SQLite for local data storage
• Schema: packages/eve/src/db/schema.ts defines all tables
• Models: Active Record pattern with helper classes for complex operations
• Migrations: Drizzle Kit handles schema migrations

EVE Online Integration

• OAuth Flow: Complete EVE SSO implementation with token management
• Scope Management: Comprehensive ESI scope definitions and validation
• Token Refresh: Automatic token refresh with scope preservation
• Data Caching: Smart caching of EVE reference data and API responses

Web Interface Architecture

• Framework: Brisa for server-side rendering with progressive enhancement
• Authentication: EVE SSO integrated at middleware level
• Components: Server-side components with suspense for async data loading
• Styling: Tailwind CSS with DaisyUI components

Design Patterns

Package Exports

Each package uses structured exports for different concerns:

// @star-kitten/eve exports
export * from "./esi"; // ESI API integration
export * as CharacterAPI from "./esi/character";
export * as models from "./models"; // Data models
export * as db from "./db"; // Database access
export * from "./third-party"; // External APIs

Error Handling

• API Errors: Consistent error wrapping for external API calls
• Token Validation: Graceful handling of expired/invalid tokens
• Database Errors: Transaction rollback and error logging

Data Processing

• Streaming: Large JSON files processed via streaming for memory efficiency
• Caching: Multi-level caching (in-memory, database, file system)
• Type Safety: Full TypeScript coverage with strict type checking

Component Relationships

Discord Bot Flow

1. main.ts initializes Dysnomia client
2. importCommands() discovers command files
3. Commands register interaction handlers on global client
4. User interactions trigger command-specific handlers

Web Authentication Flow

1. middleware.ts intercepts requests
2. EVE SSO redirect initiated for unauthenticated users
3. OAuth callback validates tokens and creates/updates user records
4. Character data synchronized from ESI API
5. Dashboard components display real-time character statistics

Data Synchronization

1. Reference data downloaded from external sources
2. JSON files processed using streaming query utilities
3. Character data fetched from ESI API
4. Local database updated with character and user information
5. Web components display cached data with real-time updates

Critical Implementation Paths

Adding New Commands

1. Create *.command.ts file in packages/eve-bot/src/commands/
2. Export Discord command definition as default
3. Add interaction handlers to global client event listeners
4. Commands automatically discovered and registered

EVE API Integration

1. Define required scopes in scopes.ts
2. Implement API client in appropriate ESI module
3. Add character model methods for data access
4. Create web components for data display

Database Schema Changes

1. Update schema.ts with new tables/columns
2. Generate migration using Drizzle Kit
3. Update model classes with new methods
4. Add database exports to db/index.ts