jb/star-kitten
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

adding freight web and holding

Browse Source
This commit is contained in:
JB
2025-12-24 00:38:53 -05:00
parent 0c8630b8ba
commit f39e9132ad
164 changed files with 5559 additions and 156655 deletions
Download Patch File Download Diff File Expand all files Collapse all files

426
.kilocode/rules/memory-bank/architecture.md
View File

@@ -1,213 +1,213 @@
# Architecture Overview - Star Kitten
## System Architecture
Star Kitten follows a modular monorepo architecture with four main packages and two applications:
```mermaid
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](packages/discord/)
- **Entry Point**: [`packages/discord/src/index.ts`](packages/discord/src/index.ts)
- **Command System**: [`packages/discord/src/commands/`](packages/discord/src/commands/)
- [`import-commands.ts`](packages/discord/src/commands/import-commands.ts) - Auto-discovery of command files
- [`handle-commands.ts`](packages/discord/src/commands/handle-commands.ts) - Command execution handler
- **Localization**: [`packages/discord/src/locales.ts`](packages/discord/src/locales.ts)
#### [@star-kitten/eve](packages/eve/)
- **Entry Point**: [`packages/eve/src/index.ts`](packages/eve/src/index.ts)
- **Database Layer**: [`packages/eve/src/db/`](packages/eve/src/db/)
- [`schema.ts`](packages/eve/src/db/schema.ts) - Drizzle ORM schema definitions
- [`index.ts`](packages/eve/src/db/index.ts) - Database connection and exports
- [`models/`](packages/eve/src/db/models/) - Character and user model helpers
- **ESI Integration**: [`packages/eve/src/esi/`](packages/eve/src/esi/)
- [`auth.ts`](packages/eve/src/esi/auth.ts) - EVE SSO authentication flow
- [`scopes.ts`](packages/eve/src/esi/scopes.ts) - ESI scope definitions and token validation
- [`character.ts`](packages/eve/src/esi/character.ts) - Character API endpoints
- [`fetch.ts`](packages/eve/src/esi/fetch.ts) - ESI API client wrapper
- **Data Models**: [`packages/eve/src/models/`](packages/eve/src/models/)
- [`type.ts`](packages/eve/src/models/type.ts) - EVE item type definitions and utilities
- [`skill.ts`](packages/eve/src/models/skill.ts) - Skill-related models
- **Third-party APIs**: [`packages/eve/src/third-party/`](packages/eve/src/third-party/)
- [`janice.ts`](packages/eve/src/third-party/janice.ts) - Market appraisal integration
- [`evetycoon.ts`](packages/eve/src/third-party/evetycoon.ts) - Market data integration
- **Utilities**: [`packages/eve/src/utils/`](packages/eve/src/utils/)
- [`markdown.ts`](packages/eve/src/utils/markdown.ts) - EVE markup to Discord formatting
#### [@star-kitten/util](packages/util/)
- **Entry Point**: [`packages/util/src/`](packages/util/src/) (no index.ts, exports individual modules)
- **Core Utilities**:
- [`text.ts`](packages/util/src/text.ts) - Text processing and formatting
- [`jsonQuery.ts`](packages/util/src/jsonQuery.ts) - Streaming JSON querying for large files
- [`time.ts`](packages/util/src/time.ts) - Time utilities
- [`logger.ts`](packages/util/src/logger.ts) - Logging utilities
- **Scheduler System**: [`packages/util/src/scheduler/`](packages/util/src/scheduler/)
- [`scheduler.service.ts`](packages/util/src/scheduler/scheduler.service.ts) - Job scheduling service
- [`queue.ts`](packages/util/src/scheduler/queue.ts) - Job queue implementation
- [`workers/`](packages/util/src/scheduler/workers/) - Background worker implementations
### Applications
#### [eve-bot](packages/eve-bot/)
- **Entry Point**: [`packages/eve-bot/src/main.ts`](packages/eve-bot/src/main.ts)
- **Commands**: [`packages/eve-bot/src/commands/`](packages/eve-bot/src/commands/)
- [`appraise.command.ts`](packages/eve-bot/src/commands/appraise.command.ts) - Market appraisal command
- **Types**: [`packages/eve-bot/src/types/global.d.ts`](packages/eve-bot/src/types/global.d.ts)
#### [eve-web](packages/eve-web/)
- **Entry Point**: [`packages/eve-web/src/pages/index.tsx`](packages/eve-web/src/pages/index.tsx)
- **Middleware**: [`packages/eve-web/src/middleware.ts`](packages/eve-web/src/middleware.ts) - EVE SSO integration
- **Components**: [`packages/eve-web/src/components/stats/`](packages/eve-web/src/components/stats/)
- [`skill-queue.tsx`](packages/eve-web/src/components/stats/skill-queue.tsx) - Real-time skill training display
- [`wallet.tsx`](packages/eve-web/src/components/stats/wallet.tsx) - Wallet balance and changes
- **API Routes**: [`packages/eve-web/src/api/auth/`](packages/eve-web/src/api/auth/) - Authentication endpoints
- **Utilities**: [`packages/eve-web/src/utils/cookies.ts`](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`](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:
```typescript
// @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`](packages/eve-bot/src/main.ts) initializes Dysnomia client
2. [`importCommands()`](packages/discord/src/commands/import-commands.ts) discovers command files
3. Commands register interaction handlers on global client
4. User interactions trigger command-specific handlers
### Web Authentication Flow
1. [`middleware.ts`](packages/eve-web/src/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/`](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`](packages/eve/src/esi/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`](packages/eve/src/db/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`](packages/eve/src/db/index.ts)
# Architecture Overview - Star Kitten
## System Architecture
Star Kitten follows a modular monorepo architecture with four main packages and two applications:
```mermaid
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](packages/discord/)
- **Entry Point**: [`packages/discord/src/index.ts`](packages/discord/src/index.ts)
- **Command System**: [`packages/discord/src/commands/`](packages/discord/src/commands/)
- [`import-commands.ts`](packages/discord/src/commands/import-commands.ts) - Auto-discovery of command files
- [`handle-commands.ts`](packages/discord/src/commands/handle-commands.ts) - Command execution handler
- **Localization**: [`packages/discord/src/locales.ts`](packages/discord/src/locales.ts)
#### [@star-kitten/eve](packages/eve/)
- **Entry Point**: [`packages/eve/src/index.ts`](packages/eve/src/index.ts)
- **Database Layer**: [`packages/eve/src/db/`](packages/eve/src/db/)
- [`schema.ts`](packages/eve/src/db/schema.ts) - Drizzle ORM schema definitions
- [`index.ts`](packages/eve/src/db/index.ts) - Database connection and exports
- [`models/`](packages/eve/src/db/models/) - Character and user model helpers
- **ESI Integration**: [`packages/eve/src/esi/`](packages/eve/src/esi/)
- [`auth.ts`](packages/eve/src/esi/auth.ts) - EVE SSO authentication flow
- [`scopes.ts`](packages/eve/src/esi/scopes.ts) - ESI scope definitions and token validation
- [`character.ts`](packages/eve/src/esi/character.ts) - Character API endpoints
- [`fetch.ts`](packages/eve/src/esi/fetch.ts) - ESI API client wrapper
- **Data Models**: [`packages/eve/src/models/`](packages/eve/src/models/)
- [`type.ts`](packages/eve/src/models/type.ts) - EVE item type definitions and utilities
- [`skill.ts`](packages/eve/src/models/skill.ts) - Skill-related models
- **Third-party APIs**: [`packages/eve/src/third-party/`](packages/eve/src/third-party/)
- [`janice.ts`](packages/eve/src/third-party/janice.ts) - Market appraisal integration
- [`evetycoon.ts`](packages/eve/src/third-party/evetycoon.ts) - Market data integration
- **Utilities**: [`packages/eve/src/utils/`](packages/eve/src/utils/)
- [`markdown.ts`](packages/eve/src/utils/markdown.ts) - EVE markup to Discord formatting
#### [@star-kitten/util](packages/util/)
- **Entry Point**: [`packages/util/src/`](packages/util/src/) (no index.ts, exports individual modules)
- **Core Utilities**:
- [`text.ts`](packages/util/src/text.ts) - Text processing and formatting
- [`jsonQuery.ts`](packages/util/src/jsonQuery.ts) - Streaming JSON querying for large files
- [`time.ts`](packages/util/src/time.ts) - Time utilities
- [`logger.ts`](packages/util/src/logger.ts) - Logging utilities
- **Scheduler System**: [`packages/util/src/scheduler/`](packages/util/src/scheduler/)
- [`scheduler.service.ts`](packages/util/src/scheduler/scheduler.service.ts) - Job scheduling service
- [`queue.ts`](packages/util/src/scheduler/queue.ts) - Job queue implementation
- [`workers/`](packages/util/src/scheduler/workers/) - Background worker implementations
### Applications
#### [eve-bot](packages/eve-bot/)
- **Entry Point**: [`packages/eve-bot/src/main.ts`](packages/eve-bot/src/main.ts)
- **Commands**: [`packages/eve-bot/src/commands/`](packages/eve-bot/src/commands/)
- [`appraise.command.ts`](packages/eve-bot/src/commands/appraise.command.ts) - Market appraisal command
- **Types**: [`packages/eve-bot/src/types/global.d.ts`](packages/eve-bot/src/types/global.d.ts)
#### [eve-web](packages/eve-web/)
- **Entry Point**: [`packages/eve-web/src/pages/index.tsx`](packages/eve-web/src/pages/index.tsx)
- **Middleware**: [`packages/eve-web/src/middleware.ts`](packages/eve-web/src/middleware.ts) - EVE SSO integration
- **Components**: [`packages/eve-web/src/components/stats/`](packages/eve-web/src/components/stats/)
- [`skill-queue.tsx`](packages/eve-web/src/components/stats/skill-queue.tsx) - Real-time skill training display
- [`wallet.tsx`](packages/eve-web/src/components/stats/wallet.tsx) - Wallet balance and changes
- **API Routes**: [`packages/eve-web/src/api/auth/`](packages/eve-web/src/api/auth/) - Authentication endpoints
- **Utilities**: [`packages/eve-web/src/utils/cookies.ts`](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`](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:
```typescript
// @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`](packages/eve-bot/src/main.ts) initializes Dysnomia client
2. [`importCommands()`](packages/discord/src/commands/import-commands.ts) discovers command files
3. Commands register interaction handlers on global client
4. User interactions trigger command-specific handlers
### Web Authentication Flow
1. [`middleware.ts`](packages/eve-web/src/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/`](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`](packages/eve/src/esi/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`](packages/eve/src/db/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`](packages/eve/src/db/index.ts)

14
.kilocode/rules/memory-bank/brief.md
View File

@@ -1,7 +1,7 @@
This project, Star Kitten, is a personal project of mine which will be a set of packges for building discord bots and websites focused on the games I play. I am starting with an eve online bot and webpage and will be building a star citizen discord bot later.
This project used bun, Dysnomia js, and currently Brisa, but I plan to change that to an Elysia server with Ripple SPA.
I use TypeScript and focus on re-usable functional components as much as I can.
I would like to do my best to maintain at least 80% coverage with all major functionality tested using bun:test.
This project, Star Kitten, is a personal project of mine which will be a set of packges for building discord bots and websites focused on the games I play. I am starting with an eve online bot and webpage and will be building a star citizen discord bot later.
This project used bun, Dysnomia js, and currently Brisa, but I plan to change that to an Elysia server with Ripple SPA.
I use TypeScript and focus on re-usable functional components as much as I can.
I would like to do my best to maintain at least 80% coverage with all major functionality tested using bun:test.

334
.kilocode/rules/memory-bank/context.md
View File

@@ -1,167 +1,167 @@
# Project Context - Star Kitten
## Current Development State
### Project Maturity
- **Phase**: Active Development
- **Version**: 0.0.0 (pre-release)
- **Status**: Core framework established, basic functionality implemented
- **Last Major Update**: Memory bank initialization (January 2025)
### Current Work Focus
- **Primary**: EVE Online Discord bot and web interface development
- **Secondary**: Framework stabilization and documentation
- **Future**: Star Citizen integration planning
### Recent Changes
- Memory bank system initialized with comprehensive documentation
- Core architecture established across four packages
- Basic EVE Online integration functional
- Discord command system with auto-discovery implemented
- Web interface with EVE SSO authentication working
## Active Features
### Discord Bot (`eve-bot`)
- **Status**: Basic functionality working
- **Commands**:
- Market appraisal command (partial implementation)
- **Authentication**: Global client setup with Dysnomia
- **Deployment**: Environment-based configuration ready
### Web Interface (`eve-web`)
- **Status**: Basic dashboard working
- **Authentication**: EVE SSO OAuth flow implemented
- **Components**:
- Skill queue display with progress tracking
- Wallet balance with daily change calculation
- **Framework**: Brisa SSR with Tailwind CSS + DaisyUI
### Core Packages
- **@star-kitten/discord**: Command auto-discovery and handling
- **@star-kitten/eve**: ESI API integration, database models, third-party APIs
- **@star-kitten/util**: Streaming JSON queries, text processing, job scheduling
## Technical Debt & Known Issues
### Architecture Decisions Pending
- **Web Framework Migration**: Planned switch from Brisa to Elysia + Ripple SPA
- **Package Versioning**: All packages at 0.0.0, versioning strategy needed
- **Testing Coverage**: Current coverage unknown, target is 80%
### Implementation Gaps
- **Command System**: [`handle-commands.ts`](packages/discord/src/commands/handle-commands.ts) references global commands object not used in current pattern
- **Appraisal Command**: Modal submission handling incomplete
- **Mining Fleet Module**: Database schema exists but no implementation
- **API Error Handling**: Needs standardization across packages
### Database Schema
- **Current Tables**: users, characters, resumeCommands, miningFleets, miningFleetParticipants
- **Migration Status**: Drizzle Kit configured but migration history unclear
- **Data Location**: SQLite database at configurable path
## Development Environment
### Setup Requirements
- **Runtime**: Bun (JavaScript runtime and package manager)
- **Language**: TypeScript with strict type checking
- **Database**: SQLite with Drizzle ORM
- **Development**: VS Code with format-on-save configuration
### Build System
- **Package Manager**: Bun workspaces
- **Build Tool**: tsdown for TypeScript compilation
- **Scripts**: Unified commands across packages (build, dev, test)
### External Dependencies
- **EVE Online**: ESI API access requires client credentials
- **Janice API**: Market appraisal service requires API key
- **Discord**: Bot token required for Discord API access
## Next Steps Priority
### Immediate (Current Sprint)
1. Complete appraisal command implementation
2. Add comprehensive error handling to ESI integration
3. Implement basic test coverage for core functionality
4. Document API authentication setup process
### Short Term (Next Month)
1. Implement mining fleet management functionality
2. Add more Discord commands (character lookup, skill planning)
3. Expand web interface with more character statistics
4. Establish proper versioning and release process
### Medium Term (Next Quarter)
1. Migrate web framework to Elysia + Ripple SPA
2. Add support for corporation and alliance management
3. Implement data synchronization and caching strategies
4. Create documentation for third-party developers
### Long Term (Next Year)
1. Star Citizen integration architecture
2. Multi-game framework abstraction
3. Plugin system for community extensions
4. Performance optimization and scaling
## Key Stakeholders
### Internal Development
- **Primary Developer**: j-b-3 (project owner and main developer)
- **Target Users**: EVE Online corporations and alliances
- **Future Contributors**: Open source community (planned)
### External Dependencies
- **CCP Games**: EVE Online ESI API provider
- **Discord**: Platform and API provider
- **Community**: EVE Online player community feedback
## Risk Assessment
### Technical Risks
- **Framework Migration**: Brisa to Elysia migration complexity
- **API Rate Limits**: EVE ESI and third-party API limitations
- **Database Performance**: SQLite scalability for large datasets
- **Token Management**: OAuth token refresh reliability
### Project Risks
- **Single Developer**: No backup maintainer currently
- **Community Adoption**: Uncertain uptake by EVE Online communities
- **Game API Changes**: Dependency on external game APIs
- **Competition**: Existing EVE Online bot solutions
## Success Metrics
### Current Measurements
- **Code Quality**: Type safety across all packages
- **Architecture**: Modular design with clear separation
- **Documentation**: Comprehensive memory bank established
- **Functionality**: Basic bot and web interface working
### Target Metrics
- **Test Coverage**: 80% across major functionality
- **Performance**: <2 second Discord command response times
- **Reliability**: 99%+ uptime for deployed services
- **Adoption**: Usage by multiple EVE Online communities
# Project Context - Star Kitten
## Current Development State
### Project Maturity
- **Phase**: Active Development
- **Version**: 0.0.0 (pre-release)
- **Status**: Core framework established, basic functionality implemented
- **Last Major Update**: Memory bank initialization (January 2025)
### Current Work Focus
- **Primary**: EVE Online Discord bot and web interface development
- **Secondary**: Framework stabilization and documentation
- **Future**: Star Citizen integration planning
### Recent Changes
- Memory bank system initialized with comprehensive documentation
- Core architecture established across four packages
- Basic EVE Online integration functional
- Discord command system with auto-discovery implemented
- Web interface with EVE SSO authentication working
## Active Features
### Discord Bot (`eve-bot`)
- **Status**: Basic functionality working
- **Commands**:
- Market appraisal command (partial implementation)
- **Authentication**: Global client setup with Dysnomia
- **Deployment**: Environment-based configuration ready
### Web Interface (`eve-web`)
- **Status**: Basic dashboard working
- **Authentication**: EVE SSO OAuth flow implemented
- **Components**:
- Skill queue display with progress tracking
- Wallet balance with daily change calculation
- **Framework**: Brisa SSR with Tailwind CSS + DaisyUI
### Core Packages
- **@star-kitten/discord**: Command auto-discovery and handling
- **@star-kitten/eve**: ESI API integration, database models, third-party APIs
- **@star-kitten/util**: Streaming JSON queries, text processing, job scheduling
## Technical Debt & Known Issues
### Architecture Decisions Pending
- **Web Framework Migration**: Planned switch from Brisa to Elysia + Ripple SPA
- **Package Versioning**: All packages at 0.0.0, versioning strategy needed
- **Testing Coverage**: Current coverage unknown, target is 80%
### Implementation Gaps
- **Command System**: [`handle-commands.ts`](packages/discord/src/commands/handle-commands.ts) references global commands object not used in current pattern
- **Appraisal Command**: Modal submission handling incomplete
- **Mining Fleet Module**: Database schema exists but no implementation
- **API Error Handling**: Needs standardization across packages
### Database Schema
- **Current Tables**: users, characters, resumeCommands, miningFleets, miningFleetParticipants
- **Migration Status**: Drizzle Kit configured but migration history unclear
- **Data Location**: SQLite database at configurable path
## Development Environment
### Setup Requirements
- **Runtime**: Bun (JavaScript runtime and package manager)
- **Language**: TypeScript with strict type checking
- **Database**: SQLite with Drizzle ORM
- **Development**: VS Code with format-on-save configuration
### Build System
- **Package Manager**: Bun workspaces
- **Build Tool**: tsdown for TypeScript compilation
- **Scripts**: Unified commands across packages (build, dev, test)
### External Dependencies
- **EVE Online**: ESI API access requires client credentials
- **Janice API**: Market appraisal service requires API key
- **Discord**: Bot token required for Discord API access
## Next Steps Priority
### Immediate (Current Sprint)
1. Complete appraisal command implementation
2. Add comprehensive error handling to ESI integration
3. Implement basic test coverage for core functionality
4. Document API authentication setup process
### Short Term (Next Month)
1. Implement mining fleet management functionality
2. Add more Discord commands (character lookup, skill planning)
3. Expand web interface with more character statistics
4. Establish proper versioning and release process
### Medium Term (Next Quarter)
1. Migrate web framework to Elysia + Ripple SPA
2. Add support for corporation and alliance management
3. Implement data synchronization and caching strategies
4. Create documentation for third-party developers
### Long Term (Next Year)
1. Star Citizen integration architecture
2. Multi-game framework abstraction
3. Plugin system for community extensions
4. Performance optimization and scaling
## Key Stakeholders
### Internal Development
- **Primary Developer**: j-b-3 (project owner and main developer)
- **Target Users**: EVE Online corporations and alliances
- **Future Contributors**: Open source community (planned)
### External Dependencies
- **CCP Games**: EVE Online ESI API provider
- **Discord**: Platform and API provider
- **Community**: EVE Online player community feedback
## Risk Assessment
### Technical Risks
- **Framework Migration**: Brisa to Elysia migration complexity
- **API Rate Limits**: EVE ESI and third-party API limitations
- **Database Performance**: SQLite scalability for large datasets
- **Token Management**: OAuth token refresh reliability
### Project Risks
- **Single Developer**: No backup maintainer currently
- **Community Adoption**: Uncertain uptake by EVE Online communities
- **Game API Changes**: Dependency on external game APIs
- **Competition**: Existing EVE Online bot solutions
## Success Metrics
### Current Measurements
- **Code Quality**: Type safety across all packages
- **Architecture**: Modular design with clear separation
- **Documentation**: Comprehensive memory bank established
- **Functionality**: Basic bot and web interface working
### Target Metrics
- **Test Coverage**: 80% across major functionality
- **Performance**: <2 second Discord command response times
- **Reliability**: 99%+ uptime for deployed services
- **Adoption**: Usage by multiple EVE Online communities

200
.kilocode/rules/memory-bank/product.md
View File

@@ -1,100 +1,100 @@
# Product Overview - Star Kitten
## What Star Kitten Is
Star Kitten is a comprehensive framework for building Discord bots and web applications focused on gaming communities, specifically MMO games like EVE Online and Star Citizen. It provides reusable packages and components that handle common gaming bot functionality including authentication, API integrations, data management, and user interfaces.
## Problems It Solves
### For Gaming Community Managers
- **Fragmented Tools**: Gaming communities often use multiple disconnected tools for different functions (Discord bots, web dashboards, data analysis)
- **Complex Authentication**: Managing OAuth flows for game APIs (EVE ESI, future Star Citizen APIs) is complex and error-prone
- **Data Integration**: Combining game data with Discord interactions and web interfaces requires significant development effort
- **Repetitive Development**: Building similar functionality across different gaming communities involves recreating the same patterns
### For Developers
- **Discord Bot Boilerplate**: Eliminates the need to write command handling, interaction management, and Discord client setup from scratch
- **Game API Complexity**: Abstracts complex game API authentication, token management, and data fetching
- **Database Management**: Provides pre-built schemas and models for common gaming bot use cases
- **Type Safety**: Offers comprehensive TypeScript definitions for all game data types and API responses
## How It Works
### Architecture Philosophy
Star Kitten follows a modular, package-based architecture where each package serves a specific purpose:
1. **[@star-kitten/discord](packages/discord/)** - Core Discord bot functionality with command handling and interaction management
2. **[@star-kitten/eve](packages/eve/)** - EVE Online specific integrations including ESI API, authentication, and data models
3. **[@star-kitten/util](packages/util/)** - Shared utilities including schedulers, text processing, and JSON querying
4. **[eve-bot](packages/eve-bot/)** - Complete EVE Online Discord bot implementation
5. **[eve-web](packages/eve-web/)** - Web interface for EVE Online bot management and statistics
### Key Workflows
#### Discord Bot Creation
1. Import command handling from `@star-kitten/discord`
2. Create command files with `.command.ts` extension
3. Bot automatically discovers and registers commands
4. Handle interactions through standardized command structure
#### EVE Online Integration
1. User authenticates via EVE SSO through web interface
2. Tokens stored securely with automatic refresh handling
3. ESI API calls abstracted through helper functions
4. Character data synchronized and cached in local database
#### Web Dashboard
1. Users authenticate via EVE SSO
2. Character data displayed through reactive components
3. Real-time statistics from ESI API
4. Admin functions for bot management
## User Experience Goals
### Discord Users
- **Intuitive Commands**: Slash commands with clear descriptions and localization support
- **Rich Interactions**: Modal forms, select menus, and interactive components for complex workflows
- **Immediate Feedback**: Fast response times with proper loading states and error handling
- **Contextual Help**: Commands provide guidance and examples for proper usage
### Web Users
- **Seamless Authentication**: Single sign-on through EVE Online credentials
- **Responsive Design**: Works well on desktop and mobile devices
- **Real-time Data**: Live updates of character stats, wallet balances, and skill queues
- **Progressive Enhancement**: Basic functionality works without JavaScript
### Bot Administrators
- **Easy Deployment**: Simple configuration through environment variables
- **Monitoring**: Built-in logging and error tracking
- **Scalability**: Modular architecture supports adding new features without breaking existing functionality
- **Data Control**: Local database with full control over user data and privacy
## Success Metrics
### Technical Success
- **Reliability**: 99%+ uptime for bot and web services
- **Performance**: < 2 second response times for Discord commands
- **Code Quality**: 80%+ test coverage maintained across all packages
- **Developer Experience**: New features can be added without modifying core packages
### User Adoption
- **Community Growth**: Framework adoption by multiple EVE Online corporations/alliances
- **Feature Usage**: High engagement with key features like appraisals, fleet management, and character tracking
- **Feedback Integration**: Regular updates based on user feedback and pain points
### Long-term Vision
- **Multi-Game Support**: Expand to Star Citizen and other MMO games
- **Ecosystem Growth**: Third-party packages extending Star Kitten functionality
- **Open Source Community**: Active contributor base improving and extending the framework
# Product Overview - Star Kitten
## What Star Kitten Is
Star Kitten is a comprehensive framework for building Discord bots and web applications focused on gaming communities, specifically MMO games like EVE Online and Star Citizen. It provides reusable packages and components that handle common gaming bot functionality including authentication, API integrations, data management, and user interfaces.
## Problems It Solves
### For Gaming Community Managers
- **Fragmented Tools**: Gaming communities often use multiple disconnected tools for different functions (Discord bots, web dashboards, data analysis)
- **Complex Authentication**: Managing OAuth flows for game APIs (EVE ESI, future Star Citizen APIs) is complex and error-prone
- **Data Integration**: Combining game data with Discord interactions and web interfaces requires significant development effort
- **Repetitive Development**: Building similar functionality across different gaming communities involves recreating the same patterns
### For Developers
- **Discord Bot Boilerplate**: Eliminates the need to write command handling, interaction management, and Discord client setup from scratch
- **Game API Complexity**: Abstracts complex game API authentication, token management, and data fetching
- **Database Management**: Provides pre-built schemas and models for common gaming bot use cases
- **Type Safety**: Offers comprehensive TypeScript definitions for all game data types and API responses
## How It Works
### Architecture Philosophy
Star Kitten follows a modular, package-based architecture where each package serves a specific purpose:
1. **[@star-kitten/discord](packages/discord/)** - Core Discord bot functionality with command handling and interaction management
2. **[@star-kitten/eve](packages/eve/)** - EVE Online specific integrations including ESI API, authentication, and data models
3. **[@star-kitten/util](packages/util/)** - Shared utilities including schedulers, text processing, and JSON querying
4. **[eve-bot](packages/eve-bot/)** - Complete EVE Online Discord bot implementation
5. **[eve-web](packages/eve-web/)** - Web interface for EVE Online bot management and statistics
### Key Workflows
#### Discord Bot Creation
1. Import command handling from `@star-kitten/discord`
2. Create command files with `.command.ts` extension
3. Bot automatically discovers and registers commands
4. Handle interactions through standardized command structure
#### EVE Online Integration
1. User authenticates via EVE SSO through web interface
2. Tokens stored securely with automatic refresh handling
3. ESI API calls abstracted through helper functions
4. Character data synchronized and cached in local database
#### Web Dashboard
1. Users authenticate via EVE SSO
2. Character data displayed through reactive components
3. Real-time statistics from ESI API
4. Admin functions for bot management
## User Experience Goals
### Discord Users
- **Intuitive Commands**: Slash commands with clear descriptions and localization support
- **Rich Interactions**: Modal forms, select menus, and interactive components for complex workflows
- **Immediate Feedback**: Fast response times with proper loading states and error handling
- **Contextual Help**: Commands provide guidance and examples for proper usage
### Web Users
- **Seamless Authentication**: Single sign-on through EVE Online credentials
- **Responsive Design**: Works well on desktop and mobile devices
- **Real-time Data**: Live updates of character stats, wallet balances, and skill queues
- **Progressive Enhancement**: Basic functionality works without JavaScript
### Bot Administrators
- **Easy Deployment**: Simple configuration through environment variables
- **Monitoring**: Built-in logging and error tracking
- **Scalability**: Modular architecture supports adding new features without breaking existing functionality
- **Data Control**: Local database with full control over user data and privacy
## Success Metrics
### Technical Success
- **Reliability**: 99%+ uptime for bot and web services
- **Performance**: < 2 second response times for Discord commands
- **Code Quality**: 80%+ test coverage maintained across all packages
- **Developer Experience**: New features can be added without modifying core packages
### User Adoption
- **Community Growth**: Framework adoption by multiple EVE Online corporations/alliances
- **Feature Usage**: High engagement with key features like appraisals, fleet management, and character tracking
- **Feedback Integration**: Regular updates based on user feedback and pain points
### Long-term Vision
- **Multi-Game Support**: Expand to Star Citizen and other MMO games
- **Ecosystem Growth**: Third-party packages extending Star Kitten functionality
- **Open Source Community**: Active contributor base improving and extending the framework

302
.kilocode/rules/memory-bank/tasks.md
View File

@@ -1,151 +1,151 @@
# Tasks - Star Kitten
## Add New Discord Command
**Last performed:** Initial setup
**Files to modify:**
- `packages/eve-bot/src/commands/[command-name].command.ts` - New command file
- Global Discord client automatically registers new commands
**Steps:**
1. Create new command file following naming convention `[name].command.ts`
2. Export Discord command definition as default export
3. Add interaction handlers using global client event listeners
4. Include localization for command names and descriptions
5. Test command registration and interaction handling
**Important notes:**
- Commands are auto-discovered using glob patterns
- Each command handles its own interactions via global client
- Follow existing pattern from `appraise.command.ts`
- Include comprehensive error handling for all interactions
## Add New EVE ESI Integration
**Last performed:** Character and wallet integration
**Files to modify:**
- `packages/eve/src/esi/[module].ts` - New ESI module
- `packages/eve/src/esi/index.ts` - Export new module
- `packages/eve/src/esi/scopes.ts` - Add required scopes if needed
- `packages/eve/src/db/models/character.model.ts` - Add helper methods if needed
**Steps:**
1. Define required ESI scopes in scopes.ts
2. Create new ESI module with fetch functions
3. Add proper TypeScript interfaces for API responses
4. Implement caching where appropriate
5. Add character model helper methods for data access
6. Update exports in index.ts
**Important notes:**
- Always handle token refresh automatically
- Include comprehensive error handling for API failures
- Follow existing patterns from character.ts and wallet integrations
- Cache responses appropriately to respect rate limits
## Database Schema Migration
**Last performed:** Initial schema setup
**Files to modify:**
- `packages/eve/src/db/schema.ts` - Schema definitions
- `packages/eve/src/db/models/` - Model helpers if needed
- `packages/eve/src/db/index.ts` - Export new tables
**Steps:**
1. Update schema.ts with new tables/columns
2. Generate migration using `bun run generate-migrations`
3. Test migration with `bun run migrate`
4. Update model classes with new methods
5. Add exports to db/index.ts
6. Update database initialization in main applications
**Important notes:**
- Always backup database before migrations
- Test migrations on development database first
- Update all references to schema changes
- Consider data migration scripts for existing data
## Add New Web Component
**Last performed:** Skill queue and wallet components
**Files to modify:**
- `packages/eve-web/src/components/[category]/[component].tsx` - New component
- `packages/eve-web/src/pages/index.tsx` - Import and use component
- Related ESI integration if data source needed
**Steps:**
1. Create new component following existing patterns
2. Implement async data loading with suspense fallback
3. Add proper TypeScript interfaces for props
4. Style using Tailwind CSS and DaisyUI components
5. Import and integrate into appropriate page
6. Test with real data and loading states
**Important notes:**
- Always provide suspense fallback for loading states
- Follow existing component patterns from skill-queue.tsx and wallet.tsx
- Use server-side rendering capabilities of Brisa
- Ensure responsive design for mobile devices
## Add Third-Party API Integration
**Last performed:** Janice API integration
**Files to modify:**
- `packages/eve/src/third-party/[service].ts` - New API integration
- `packages/eve/src/third-party/index.ts` - Export new service
- Environment configuration for API keys
**Steps:**
1. Create new service module with TypeScript interfaces
2. Implement API client with proper error handling
3. Add caching layer for performance
4. Include comprehensive validation for inputs/outputs
5. Add tests for all API functions
6. Update exports and environment configuration
**Important notes:**
- Always implement proper rate limiting and caching
- Include comprehensive error handling and validation
- Follow existing patterns from janice.ts
- Add API key management through environment variables
- Test with real API to ensure compatibility
## Update Reference Data
**Last performed:** Initial data setup
**Files to modify:**
- `data/reference-data/` - Static reference files
- `data/hoboleaks/` - SDE data files
- `packages/eve/src/models/` - Data model updates if needed
**Steps:**
1. Run `bun get-data` to download latest reference data
2. Verify data integrity and format consistency
3. Update data models if schema changes detected
4. Test applications with new reference data
5. Commit updated data files to repository
**Important notes:**
- Reference data updates can be large (hundreds of MB)
- Always verify data integrity before committing
- Test critical functionality after data updates
- Consider data migration scripts for breaking changes
- Monitor for EVE Online patch changes that affect data structure
# Tasks - Star Kitten
## Add New Discord Command
**Last performed:** Initial setup
**Files to modify:**
- `packages/eve-bot/src/commands/[command-name].command.ts` - New command file
- Global Discord client automatically registers new commands
**Steps:**
1. Create new command file following naming convention `[name].command.ts`
2. Export Discord command definition as default export
3. Add interaction handlers using global client event listeners
4. Include localization for command names and descriptions
5. Test command registration and interaction handling
**Important notes:**
- Commands are auto-discovered using glob patterns
- Each command handles its own interactions via global client
- Follow existing pattern from `appraise.command.ts`
- Include comprehensive error handling for all interactions
## Add New EVE ESI Integration
**Last performed:** Character and wallet integration
**Files to modify:**
- `packages/eve/src/esi/[module].ts` - New ESI module
- `packages/eve/src/esi/index.ts` - Export new module
- `packages/eve/src/esi/scopes.ts` - Add required scopes if needed
- `packages/eve/src/db/models/character.model.ts` - Add helper methods if needed
**Steps:**
1. Define required ESI scopes in scopes.ts
2. Create new ESI module with fetch functions
3. Add proper TypeScript interfaces for API responses
4. Implement caching where appropriate
5. Add character model helper methods for data access
6. Update exports in index.ts
**Important notes:**
- Always handle token refresh automatically
- Include comprehensive error handling for API failures
- Follow existing patterns from character.ts and wallet integrations
- Cache responses appropriately to respect rate limits
## Database Schema Migration
**Last performed:** Initial schema setup
**Files to modify:**
- `packages/eve/src/db/schema.ts` - Schema definitions
- `packages/eve/src/db/models/` - Model helpers if needed
- `packages/eve/src/db/index.ts` - Export new tables
**Steps:**
1. Update schema.ts with new tables/columns
2. Generate migration using `bun run generate-migrations`
3. Test migration with `bun run migrate`
4. Update model classes with new methods
5. Add exports to db/index.ts
6. Update database initialization in main applications
**Important notes:**
- Always backup database before migrations
- Test migrations on development database first
- Update all references to schema changes
- Consider data migration scripts for existing data
## Add New Web Component
**Last performed:** Skill queue and wallet components
**Files to modify:**
- `packages/eve-web/src/components/[category]/[component].tsx` - New component
- `packages/eve-web/src/pages/index.tsx` - Import and use component
- Related ESI integration if data source needed
**Steps:**
1. Create new component following existing patterns
2. Implement async data loading with suspense fallback
3. Add proper TypeScript interfaces for props
4. Style using Tailwind CSS and DaisyUI components
5. Import and integrate into appropriate page
6. Test with real data and loading states
**Important notes:**
- Always provide suspense fallback for loading states
- Follow existing component patterns from skill-queue.tsx and wallet.tsx
- Use server-side rendering capabilities of Brisa
- Ensure responsive design for mobile devices
## Add Third-Party API Integration
**Last performed:** Janice API integration
**Files to modify:**
- `packages/eve/src/third-party/[service].ts` - New API integration
- `packages/eve/src/third-party/index.ts` - Export new service
- Environment configuration for API keys
**Steps:**
1. Create new service module with TypeScript interfaces
2. Implement API client with proper error handling
3. Add caching layer for performance
4. Include comprehensive validation for inputs/outputs
5. Add tests for all API functions
6. Update exports and environment configuration
**Important notes:**
- Always implement proper rate limiting and caching
- Include comprehensive error handling and validation
- Follow existing patterns from janice.ts
- Add API key management through environment variables
- Test with real API to ensure compatibility
## Update Reference Data
**Last performed:** Initial data setup
**Files to modify:**
- `data/reference-data/` - Static reference files
- `data/hoboleaks/` - SDE data files
- `packages/eve/src/models/` - Data model updates if needed
**Steps:**
1. Run `bun get-data` to download latest reference data
2. Verify data integrity and format consistency
3. Update data models if schema changes detected
4. Test applications with new reference data
5. Commit updated data files to repository
**Important notes:**
- Reference data updates can be large (hundreds of MB)
- Always verify data integrity before committing
- Test critical functionality after data updates
- Consider data migration scripts for breaking changes
- Monitor for EVE Online patch changes that affect data structure

498
.kilocode/rules/memory-bank/tech.md
View File

@@ -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