Skip to content

Commit c27826a

Browse files
mythzmythz
committed
Add CLAUDE.md
1 parent 42ce066 commit c27826a

1 file changed

Lines changed: 340 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 340 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,340 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
**ComfyGateway** - A server gateway and UI to manage and execute ComfyUI workflows. This is a full-stack application built with ServiceStack (C#/.NET 8) backend and a Vue 3 frontend (with planned migration to Next.js 16).
8+
9+
## Technology Stack
10+
11+
### Backend
12+
- **Framework**: ASP.NET Core 8.0 with ServiceStack
13+
- **Database**: PostgreSQL (production), SQLite (development/testing)
14+
- **ORM**: ServiceStack.OrmLite
15+
- **Authentication**: ASP.NET Core Identity with OAuth (Google)
16+
- **Background Jobs**: ServiceStack.Jobs with Commands pattern
17+
- **Container**: Docker with multi-stage build
18+
19+
### Frontend (Current)
20+
- **Framework**: Vue 3 SPA with TypeScript
21+
- **Build**: Bun runtime, TailwindCSS
22+
- **State**: IndexedDB for offline caching
23+
- **API Client**: ServiceStack JsonServiceClient with auto-generated DTOs
24+
25+
### Frontend (Planned Migration)
26+
- See [MIGRATION_PLAN.md](MIGRATION_PLAN.md) for complete Next.js 16 migration strategy
27+
28+
## Project Structure
29+
30+
```
31+
ubixar.com/
32+
├── MyApp/ # Main ASP.NET Core web application
33+
│ ├── wwwroot/ # Static files, Vue SPA
34+
│ │ ├── mjs/ # TypeScript modules, DTOs
35+
│ │ ├── pages/ # Vue components
36+
│ │ ├── css/ # Tailwind output
37+
│ │ └── data/ # Static data files
38+
│ ├── Components/ # Blazor components
39+
│ ├── Configure.*.cs # Modular app configuration
40+
│ └── Program.cs # Application entry point
41+
│
42+
├── MyApp.ServiceModel/ # Request/Response DTOs, domain models
43+
│ ├── Comfy.cs # Comfy workflow DTOs
44+
│ ├── Artifacts.cs # Artifact/Asset models
45+
│ ├── Agent.cs # Agent/Device models
46+
│ ├── Thread.cs # Thread conversation models
47+
│ └── ...
48+
│
49+
├── MyApp.ServiceInterface/ # Service implementations
50+
│ ├── ComfyServices.cs # Workflow execution services
51+
│ ├── ArtifactServices.cs # Artifact management
52+
│ ├── DeviceServices.cs # Device pool management
53+
│ ├── AgentServices.cs # Agent communication
54+
│ ├── AdminServices.cs # Admin operations
55+
│ ├── AppData.cs # In-memory data cache
56+
│ ├── Commands/ # Background job commands
57+
│ └── ...
58+
│
59+
├── MyApp.Tests/ # NUnit test suite
60+
│ ├── workflows/ # Test workflow JSON files
61+
│ └── ...
62+
│
63+
└── App_Data/ # Application data directory
64+
├── db.sqlite # Development SQLite DB
65+
├── jobs/ # Background job queue DB
66+
└── uploads/ # File uploads
67+
```
68+
69+
## Common Development Commands
70+
71+
### Running the Application
72+
73+
```bash
74+
# Development with hot reload (C# backend + Vue frontend)
75+
cd MyApp
76+
dotnet watch
77+
78+
# Build frontend CSS
79+
npm run ui:build # Production build
80+
npm run ui:dev # Watch mode
81+
82+
# Generate TypeScript DTOs from C# ServiceModel
83+
npm run dtos # Runs: x mjs
84+
```
85+
86+
### Database Operations
87+
88+
```bash
89+
cd MyApp
90+
91+
# Run migrations
92+
npm run migrate # Runs: dotnet run --AppTasks=migrate
93+
94+
# Revert last migration
95+
npm run revert:last
96+
97+
# Revert all migrations
98+
npm run revert:all
99+
100+
# Rerun last migration (revert + migrate)
101+
npm run rerun:last
102+
103+
# Initialize Entity Framework
104+
npm run init-ef
105+
```
106+
107+
### Testing
108+
109+
```bash
110+
# Run all tests
111+
cd MyApp.Tests
112+
dotnet test
113+
114+
# Run specific test class
115+
dotnet test --filter "FullyQualifiedName~ComfyWorkflowParseTests"
116+
117+
# Run tests with verbose output
118+
dotnet test --logger "console;verbosity=detailed"
119+
```
120+
121+
### Building & Deployment
122+
123+
```bash
124+
# Build solution
125+
dotnet build
126+
127+
# Publish application
128+
cd MyApp
129+
dotnet publish -c Release -o ./publish
130+
131+
# Build Docker image
132+
docker build -t ubixar .
133+
134+
# Run with Docker Compose
135+
docker-compose up
136+
```
137+
138+
## Architecture Overview
139+
140+
### ServiceStack Service Layer
141+
142+
This application follows the ServiceStack pattern where:
143+
144+
1. **DTOs** (`MyApp.ServiceModel/`) define the API contract
145+
2. **Services** (`MyApp.ServiceInterface/`) implement business logic
146+
3. **AutoQuery** enables automatic CRUD APIs for query operations
147+
4. **Commands** handle background jobs (email, workflows, achievements)
148+
149+
All ServiceStack services automatically get:
150+
- REST endpoints (JSON/XML/JSV)
151+
- gRPC endpoints
152+
- Message queue support
153+
- Auto-generated metadata and DTOs
154+
155+
### Database Architecture
156+
157+
**Primary Database** (configurable via `DefaultConnection` connection string):
158+
- Stores users, workflows, generations, artifacts, devices
159+
- Uses ORM-lite with code-first migrations in `Configure.Db.Migrations.cs`
160+
- Partitioned tables for large datasets (ComfyJob, PromptTask)
161+
162+
**Jobs Database** (separate SQLite or PostgreSQL):
163+
- Managed by ServiceStack.Jobs
164+
- Stores background job queue and execution history
165+
- Independent of main application database
166+
167+
### Background Jobs System
168+
169+
Uses ServiceStack.Jobs with Commands pattern:
170+
- `ExecuteComfyApiPromptCommand` - Queue ComfyUI workflow execution
171+
- `OpenAiChatCommand` - Process AI chat interactions
172+
- `ArtifactReactionAchievementCommands` - Award achievements
173+
- Background jobs run via `JobsHostedService` with 10-second tick interval
174+
175+
### AppData Caching Layer
176+
177+
`AppData.cs` maintains in-memory cache of frequently accessed data:
178+
- Workflows and workflow versions
179+
- Artifacts (featured, best rated)
180+
- Tags, models, devices
181+
- Reloaded on app startup and after admin changes
182+
- Dramatically reduces database queries for read-heavy operations
183+
184+
### Authentication & Authorization
185+
186+
- **ASP.NET Core Identity** for user management
187+
- **OAuth providers**: Google (configurable in appsettings.json)
188+
- **Roles**: Admin, Moderator (defined in `AppRoles.cs`)
189+
- **API Key Auth**: Supports `AdminAuthSecret` for service-to-service calls
190+
- Sessions stored in cookies, synced to client localStorage
191+
192+
### ComfyUI Integration
193+
194+
The gateway communicates with ComfyUI agents:
195+
- `ComfyGateway.cs` - HTTP client for ComfyUI API
196+
- `ComfyWorkflowParser.cs` - Parse ComfyUI workflow JSON
197+
- `ComfyWorkflowConverter.cs` - Convert between formats (C#/Node/Prompt)
198+
- `AgentEventsManager.cs` - WebSocket communication with agents
199+
- Device pool management for distributed processing
200+
201+
### Frontend-Backend Communication
202+
203+
1. **DTO Generation**: `x mjs` command generates `wwwroot/mjs/dtos.ts` from C# DTOs
204+
2. **Type-safe API calls**: `JsonServiceClient` uses generated DTOs
205+
3. **Real-time updates**: Long-polling via `WaitForMyWorkflowGenerations` API
206+
4. **Offline support**: IndexedDB caches workflows, generations, artifacts
207+
208+
## Key Configuration Files
209+
210+
### appsettings.json
211+
212+
```json
213+
{
214+
"AppConfig": {
215+
"AppName": "ubixar.com",
216+
"ArtifactsPath": "./App_Data/artifacts",
217+
"FilesPath": "./App_Data/files",
218+
"LocalBaseUrl": "https://localhost:5001",
219+
"PublicBaseUrl": "https://ubixar.com",
220+
"DefaultConnection": "connection-string",
221+
"GoogleClientId": "...",
222+
"GoogleClientSecret": "..."
223+
}
224+
}
225+
```
226+
227+
### Environment Variables
228+
229+
- `COMFY_DB_CONNECTION` - Override default database connection
230+
- `COMFY_GATEWAY_ARTIFACTS` - Path to artifacts storage
231+
- `AI_FILES_PATH` - Path to file uploads
232+
- `AI_SERVER_API_KEY` - Admin API key
233+
- `BUN_EXE_PATH` - Path to Bun executable
234+
235+
### Docker Compose
236+
237+
The `compose.yml` defines:
238+
- **app**: Main application (port 8080)
239+
- **db**: PostgreSQL database (port 5432)
240+
- Persistent volumes for database and App_Data
241+
242+
## Testing Strategy
243+
244+
### Test Organization
245+
246+
- `UnitTest.cs` - Pure unit tests
247+
- `IntegrationTest.cs` - Tests with database and services
248+
- `ComfyWorkflowParseTests.cs` - Workflow parsing logic
249+
- `ComfyWorkflowExecuteTests.cs` - Workflow execution flows
250+
- `OpenAiChatTests.cs` - AI chat integration
251+
252+
### Test Data
253+
254+
Test workflows stored in `MyApp.Tests/workflows/` directory with real ComfyUI workflow JSON files for validation.
255+
256+
## ServiceStack.Jobs Usage
257+
258+
Background jobs are scheduled and executed via Commands:
259+
260+
```csharp
261+
// Enqueue a one-time job
262+
jobs.EnqueueCommand<ExecuteComfyApiPromptCommand>(request);
263+
264+
// Schedule recurring job
265+
jobs.RecurringCommand<MyCommand>(Schedule.Hourly);
266+
```
267+
268+
Jobs are processed by `JobsHostedService` which ticks every 10 seconds.
269+
270+
## Common Patterns
271+
272+
### Service Implementation
273+
274+
```csharp
275+
public class MyServices : Service
276+
{
277+
public object Any(MyRequest request)
278+
{
279+
// Access database
280+
using var db = Db;
281+
var result = db.Select<MyTable>();
282+
283+
// Return response
284+
return new MyResponse { Results = result };
285+
}
286+
}
287+
```
288+
289+
### AutoQuery
290+
291+
Many queries use AutoQuery for automatic CRUD:
292+
293+
```csharp
294+
[Route("/api/workflows")]
295+
public class QueryWorkflows : QueryDb<Workflow> {}
296+
```
297+
298+
This automatically generates:
299+
- Filtering, sorting, pagination
300+
- Response caching
301+
- Multiple serialization formats
302+
303+
### Admin-only Operations
304+
305+
```csharp
306+
[ValidateHasRole(AppRoles.Admin)]
307+
public class AdminRequest : IReturn<AdminResponse> {}
308+
```
309+
310+
## Important Notes
311+
312+
- **DTO Regeneration**: Run `npm run dtos` after modifying `MyApp.ServiceModel/` DTOs
313+
- **Database Migrations**: Migrations live in `Configure.Db.Migrations.cs`, not EF Core Migrations folder
314+
- **AppData Reload**: After admin changes to workflows/artifacts, call `AppData.Instance.Reload(db)`
315+
- **Background Jobs Database**: Separate from main DB, configured in `Configure.BackgroundJobs.cs`
316+
- **Tailwind Builds**: Must run `npm run ui:build` before publishing to generate CSS
317+
318+
## Debugging
319+
320+
### VSCode Launch Configuration
321+
322+
The `.vscode/launch.json` includes:
323+
- **.NET Core Launch (web)**: Debug the application
324+
- **.NET Core Attach**: Attach to running process
325+
326+
### Useful Debugging Endpoints
327+
328+
- `/metadata` - ServiceStack metadata page (all APIs)
329+
- `/ui` - Locode Admin UI
330+
- `/health` - Health check endpoint
331+
332+
## Migration to Next.js
333+
334+
A comprehensive migration plan exists in [MIGRATION_PLAN.md](MIGRATION_PLAN.md). Key points:
335+
336+
- Next.js 16 will be a **pure UI layer** - no backend logic
337+
- All data flows through existing C# ServiceStack APIs
338+
- Static export builds to `./MyApp/wwwroot` for C# hosting
339+
- Maintains TypeScript DTOs and JsonServiceClient pattern
340+
- Preserves IndexedDB caching architecture

0 commit comments

Comments
 (0)