2026 update

.gitignore

@@ -1,9 +1,13 @@
+
 .idea
 .DS_store
 secrets.env
+*-secrets.yaml
+*secrets*.yaml
 *.module.css*
 etc/cloudflare/**/*.yml
 etc/cloudflare/**/*.json
 *.pyc
 node_modules
 .vscode/settings.json
+/infra/charts/**

CLAUDE.md

@@ -0,0 +1,171 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Morpheus is an open-source web platform for AI image generation using Stable Diffusion. It is a multi-service monorepo where each service is independently containerized and orchestrated via Docker Compose locally, and deployed to AWS EKS in production.
+
+## Services and Architecture
+
+```
+morpheus-client (Next.js, port 3000)
+morpheus-admin  (Next.js, port 3001)
+morpheus-collaborative (Node.js/Socket.io, port 3002)
+     |
+morpheus-server (FastAPI, port 8001)
+     |                  |                |
+PostgreSQL (5432)   AWS S3         morpheus-worker (Ray, ports 8000/8265)
+                                        |
+                                  Firebase (Auth/Collab)
+```
+
+- **morpheus-server** is the FastAPI backend. It owns all SQLAlchemy models, Pydantic schemas, Alembic migrations, and S3/Firebase repository implementations.
+- **morpheus-worker** runs a Ray cluster for GPU-accelerated Stable Diffusion inference.
+- The client uses Firebase for authentication and Socket.io for real-time collaboration.
+
+## Development Commands
+
+### Starting the environment
+
+```bash
+# Copy secrets templates and fill in values
+cp morpheus-server/secrets.env.dist morpheus-server/secrets.env
+cp morpheus-client/env.local.dist morpheus-client/.env.local
+cp morpheus-client/env.local.dist morpheus-admin/.env.local
+
+# Apply DB migrations (required before first start)
+docker compose run --rm api alembic upgrade head
+
+# Start all services
+docker compose up
+
+# Start specific services
+docker compose up api client admin
+```
+
+### Backend (morpheus-server)
+
+```bash
+# Run all tests
+docker compose run --rm api pytest
+
+# Run a single test file
+docker compose run --rm api pytest tests/test_module.py
+
+# Run a single test
+docker compose run --rm api pytest tests/test_module.py::test_function
+
+# Lint
+docker compose run --rm api flake8 --max-line-length 120 --exclude app/migrations/ .
+
+# Format
+docker compose run --rm api black --line-length 120 --exclude app/migrations/ .
+```
+
+### Database migrations
+
+```bash
+# Auto-generate a migration from model changes
+docker compose run --rm api alembic revision --autogenerate -m "Description"
+
+# Apply pending migrations
+docker compose run --rm api alembic upgrade head
+```
+
+### Frontend (morpheus-client / morpheus-admin)
+
+```bash
+# Lint
+docker compose exec client yarn lint
+docker compose exec admin yarn lint
+
+# Direct yarn usage (outside Docker)
+cd morpheus-client && yarn dev    # port 3000
+cd morpheus-admin   && yarn dev   # port 3001
+```
+
+### Collaborative server
+
+```bash
+docker compose exec collaborative yarn test:code  # ESLint
+docker compose exec collaborative yarn fix        # Prettier + ESLint fix
+```
+
+### Building Docker images
+
+```bash
+docker compose build api
+docker compose build client admin collaborative
+
+# Build all
+docker compose build
+```
+
+### Model management CLI
+
+```bash
+docker compose --profile manage build          # build the model-script service
+docker compose run --rm model-script --help
+docker compose run --rm model-script s3 list
+docker compose run --rm model-script db register <server> <target>
+```
+
+## Code Architecture Details
+
+### morpheus-server structure
+
+```
+app/
+  api/          # FastAPI route handlers (thin layer, delegates to services)
+  services/     # Business logic
+  models/       # SQLAlchemy ORM models and Pydantic schemas
+  repository/   # Database and S3 repository classes
+  registry/     # Model registry (HuggingFace, S3)
+  database/     # DB engine, session, init data
+  integrations/ # Third-party integrations
+  utils/        # Image helpers, timer, decorators
+  config.py     # Pydantic Settings (reads from secrets.env)
+  app.py        # FastAPI app setup, router registration
+migrations/     # Alembic migrations
+main.py         # Uvicorn entry point
+```
+
+### Key configuration
+
+| File | Purpose |
+|------|---------|
+| `morpheus-server/secrets.env` | Backend secrets (DB, Firebase, AWS, Ray URL) |
+| `morpheus-client/.env.local` | Frontend env (API URL, Firebase config, WS URL) |
+| `morpheus-server/app/config.py` | Pydantic Settings class |
+| `morpheus-worker/models.yaml` | Ray Serve deployment configuration |
+| `docker-compose.yaml` | Service orchestration for local dev |
+
+### Python code standards
+
+- Black formatter with `--line-length 120`
+- Flake8 with `--max-line-length 120 --exclude app/migrations/`
+- Alembic migrations live in `morpheus-server/migrations/`
+
+### TypeScript/JavaScript code standards
+
+- ESLint for both frontend apps and collaborative server
+- Prettier for collaborative server (`yarn fix`)
+
+## Commit conventions
+
+Follow Conventional Commits:
+- `feat:` new feature
+- `fix:` bug fix
+- `chore:` tooling/deps
+- `docs:` documentation
+- `refactor:` restructuring
+- `test:` tests
+- `perf:` performance
+
+## Infrastructure
+
+- Production runs on AWS EKS (Kubernetes), provisioned with Terraform in `infra/`
+- Helm charts are in `infra/charts/`
+- CI/CD is via GitHub Actions (`.github/workflows/`); `monorepo/cicd.py` detects which services changed to run targeted pipelines
+- Monitoring: Sentry (errors), Ray Dashboard (port 8265), Prometheus/Grafana (production)

README.md

@@ -235,6 +235,18 @@ The Morpheus project will be running on your local machine at localhost:3000 (cl
 localhost:8001 (api). Morpheus uses some Stable Diffusion models by default, if you want to change the setup you
 can do it from the administration panel.
 
+## Local Service URLs
+
+Once running, the services are available at:
+
+| Service | URL |
+|---|---|
+| Frontend (morpheus-client) | http://localhost:3000 |
+| Admin panel (morpheus-admin) | http://localhost:3001 |
+| Backend API (morpheus-server) | http://localhost:8001 |
+| Worker panel (Ray Dashboard) | http://localhost:8265 |
+| PGAdmin | http://localhost:8002 |
+
 # Development
 
 ## Running the backend tests

docker-compose.yaml

@@ -1,4 +1,3 @@
-version: "3.8"
 services:
   postgres:
     image: postgres:15-alpine
@@ -30,8 +29,6 @@ services:
     build:
       context: morpheus-server
       dockerfile: ./Dockerfile
-      args:
-        - TAG=${TAG:-latest}
     image: morpheus-server:latest
     env_file:
       - morpheus-server/secrets.env
@@ -47,22 +44,6 @@ services:
     depends_on:
       postgres:
         condition: service_healthy
-      datalib:
-        condition: service_completed_successfully
-
-  datalib:
-    build:
-      context: morpheus-data
-      dockerfile: ./Dockerfile
-      args:
-        DOCKER_BUILDKIT: 1
-    image: monadicalsas/morpheus-data:${TAG:-latest}
-    volumes:
-      - ./wheels:/wheels
-      - ./morpheus-data:/app
-    depends_on:
-      postgres:
-        condition: service_healthy
 
   client:
     build:
@@ -124,10 +105,11 @@ services:
       api:
         condition: service_started
     healthcheck:
-      test: [ "CMD-SHELL", "ray status" ]
-      interval: 5s
-      timeout: 5s
-      retries: 10
+      test: [ "CMD-SHELL", "curl -sf http://localhost:8000/ > /dev/null" ]
+      interval: 15s
+      timeout: 10s
+      retries: 20
+      start_period: 60s
     # If you don't have a gpu, comment the deploy section below
     deploy:
       resources:
@@ -136,14 +118,6 @@ services:
             - count: 1
               capabilities: [ gpu ]
 
-  worker-ray-deployer:
-    image: morpheus-worker:latest
-    command: bash -c "sleep 10 && ray job submit -- serve deploy models.yaml"
-    environment:
-      - RAY_ADDRESS=http://worker-ray:8265
-    depends_on:
-      worker-ray:
-        condition: service_healthy
 
   cloudflare-api:
     image: cloudflare/cloudflared
@@ -171,8 +145,6 @@ services:
     build:
       context: morpheus-server
       dockerfile: ./scripts/models/Dockerfile
-      args:
-        - TAG=${TAG:-latest}
     image: morpheus-script-model:latest
     profiles: [ "manage" ]
     env_file:
@@ -181,9 +153,6 @@ services:
       - ./morpheus-server:/opt/api
     stdin_open: true
     tty: true
-    depends_on:
-      datalib:
-        condition: service_completed_successfully
 
 volumes:
   pg_data:

morpheus-admin/Dockerfile

@@ -1,22 +1,12 @@
-ARG BUILD_ENV="copy"
-FROM debian:latest as base
+ARG BUILD_ENV="no_copy"
+FROM node:20-slim as base
 
 ENV LC_ALL C.UTF-8
 ENV LANG C.UTF-8
-ENV NODE_MAJOR=18
 
 ENV CLIENT_ROOT "/app"
 
-# Install system requirements
-RUN apt-get update && apt-get install -y \
-    curl ca-certificates curl gnupg && \
-    rm -rf /var/lib/apt/lists/*
-
-RUN curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
-RUN echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list
-RUN apt-get update && apt-get install nodejs -y
-
-RUN npm install --global npm yarn next sass
+RUN npm install --global next sass
 
 WORKDIR ${CLIENT_ROOT}
 

morpheus-admin/components/atoms/Brand/Brand.tsx

@@ -1,5 +1,4 @@
 import React, { CSSProperties } from "react";
-import styles from "./Brand.module.scss";
 
 interface BrandProps {
   onClick?: () => void;
@@ -10,7 +9,7 @@ const Brand = (props: BrandProps) => {
   return (
     <h2
       onClick={props.onClick}
-      className={`headline-1 ${styles.morpheusTitle}`}
+      className="morpheus-title"
       style={props.styles}
     >
       Morpheus Admin

morpheus-admin/components/atoms/Separator/Separator.tsx

@@ -1,12 +1,11 @@
 import React from "react";
-import styles from "./Separator.module.scss";
 
 export const Separator = () => {
   return (
-    <div className={styles.separator}>
-      <div className={styles.separatorLine} />
-      <span className={`caption-1 white ${styles.separatorText}`}>OR</span>
-      <div className={styles.separatorLine} />
+    <div className="w-full h-auto flex items-center text-center my-8">
+      <div className="flex-1 border border-[#f1f1f1]" />
+      <span className="caption-1 white mx-6">OR</span>
+      <div className="flex-1 border border-[#f1f1f1]" />
     </div>
   );
 };