Isekai Core

Open source DeviantArt posting management platform with scheduling, draft management, ComfyUI integration, and robust publishing automation.

Isekai is a modern web application that helps artists manage their DeviantArt posting workflow with features like scheduled publishing, draft organization, and AI image generation integration through ComfyUI.

---

📚 Documentation

For comprehensive documentation, see .context/substrate.md

The .context/ directory contains complete documentation following the Substrate Methodology:

• Architecture - System design and patterns
• API Reference - All 19 route groups documented
• Database Schema - Complete Prisma schema
• Features - Automation, publishing, browse, sales
• Development - Setup, testing, and contribution workflow
• Code Style - Conventions and patterns

AI tools: See CLAUDE.md for entry point.

---

Features

• DeviantArt Integration: OAuth authentication and seamless posting
• Scheduled Publishing: Plan and automate your DeviantArt posts
• Draft Management: Organize and edit your artwork before publishing
• ComfyUI Integration: Generate and manage AI artwork -- check out Isekai Comfy Node
• Cloud Storage: Cloudflare R2 for reliable file storage

Tech Stack

Frontend (React App)

• Framework: React 18 with TypeScript
• Build Tool: Vite 6
• Styling: Tailwind CSS 3
• Routing: React Router
• State Management: React Query (TanStack Query)

Backend (API)

• Runtime: Node.js 20+
• Framework: Express.js
• Language: TypeScript
• Database: PostgreSQL 16 with Prisma ORM
• Cache/Sessions: Redis 7
• Authentication: OAuth 2.0 (DeviantArt)
• Storage: Cloudflare R2 (S3-compatible)
• Job Queue: BullMQ

Publisher Worker (Microservice)

• Runtime: Node.js 20+
• Architecture: Dedicated background job processor
• Queue: BullMQ with Redis
• Features: Fault isolation, independent scaling, graceful shutdown
• Monitoring: Health check endpoints (/health, /ready, /metrics)

Prerequisites

• Node.js 20+
• pnpm 9+
• Docker & Docker Compose
• PostgreSQL 16 (or use Docker)
• Redis 7 (or use Docker)
• Prisma CLI (installed via pnpm)
• DeviantArt Application -- register your own app at https://www.deviantart.com/developers/apps
• Cloudflare R2 credentials, free tier is enough for testing

Quick Start

Running Docker with pre-built image

# Clone the repository
git clone https://github.com/isekai-sh/isekai-core.git
cd isekai-core

# Copy and edit your environment variables
cp .env.example .env

# Start the Docker container
docker compose up --build

The application will be available at:

• Frontend (React): http://localhost:3000
• Backend (API): http://localhost:4000
• Publisher (Health): http://localhost:8000

Building Docker image locally

# Development: build locally and run
docker-compose -f docker-compose.local.yml up --build

Project Structure

isekai/
├── apps/
│   ├── isekai-backend/     # Express backend API (port 4000)
│   ├── isekai-frontend/    # React frontend application (port 3000)
│   └── isekai-publisher/   # DeviantArt publishing worker (microservice)
├── packages/
│   └── shared/             # Shared types and database schema
├── docker-compose.yml      # Local development services
└── pnpm-workspace.yaml     # Monorepo configuration

Development

# Install dependencies
pnpm install

# Start database and Redis with Docker
docker-compose up -d postgres redis

# Set up individual environment variables
cp apps/isekai-backend/.env.example apps/isekai-backend/.env
cp apps/isekai-frontend/.env.example apps/isekai-frontend/.env
cp apps/isekai-publisher/.env.example apps/isekai-publisher/.env
cp packages/shared/.env.example packages/shared/.env

# Run database migrations
pnpm db:migrate

# Start development servers
pnpm dev

Available Scripts

# Development
pnpm dev              # Start all apps in parallel
pnpm dev:frontend     # Start frontend only
pnpm dev:backend      # Start backend only
pnpm dev:publisher    # Start publisher worker only
pnpm dev:services     # Start API + Publisher together

# Building
pnpm build            # Build all apps
pnpm build:frontend   # Build frontend
pnpm build:backend    # Build backend
pnpm build:publisher  # Build publisher worker

# Database
pnpm db:generate      # Generate database migrations
pnpm db:migrate       # Apply database migrations
pnpm db:studio        # Open Prisma Studio GUI

# Quality
pnpm lint             # Lint all apps
pnpm clean            # Clean build artifacts

Docker Services

# Start all services
docker-compose up -d

# Start specific services
docker-compose up -d postgres redis

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

# Stop and remove volumes
docker-compose down -v

Running on Low-RAM VPS (1GB)

Isekai can run on budget VPS with 1GB RAM using memory optimization. This requires:

Memory Configuration

Create a .env file with these optimized values:

# PostgreSQL Memory (total: ~180MB)
MEMORY_LIMIT_POSTGRES=180M
MEMORY_RESERVE_POSTGRES=64M
POSTGRES_SHARED_BUFFERS=64MB
POSTGRES_MAX_CONNECTIONS=20
POSTGRES_WORK_MEM=2MB

# Redis Memory (total: ~50MB)
MEMORY_LIMIT_REDIS=50M
REDIS_MAX_MEMORY=32mb

# Backend Node.js (total: ~256MB)
MEMORY_LIMIT_BACKEND=256M
NODE_OPTIONS=--max-old-space-size=256
DB_POOL_SIZE=4

# Publisher Worker (total: ~192MB)
MEMORY_LIMIT_PUBLISHER=192M
PUBLISHER_CONCURRENCY=2

# Frontend nginx (total: ~50MB)
MEMORY_LIMIT_FRONTEND=50M

Total memory usage: ~730MB + OS overhead = ~850-900MB peak usage

System Requirements for 1GB VPS

1. Add swap file (critical to prevent OOM kills):

# Create 2GB swap file
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# Reduce swappiness (prefer RAM, use swap as safety net)
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

2. Use lightweight OS: Ubuntu Server 22.04 minimal or Alpine Linux

3. Disable unnecessary services: Remove snapd, unattended-upgrades if not needed

Expected Performance

• Memory: 700-850MB used, 150-300MB free (+ 2GB swap)
• CPU: Low usage (~5-15% idle, peaks during publishing)
• Publishing: 2 concurrent jobs (slower than 2GB+ VPS)
• Response time: Acceptable for 1-3 users

When to Upgrade

Upgrade to 2GB+ VPS if you experience:

• Frequent OOM kills (check dmesg | grep oom)
• Swap usage consistently >500MB (free -h)
• Slow response times (>2s for API calls)
• Publishing job failures due to timeouts

Documentation

Complete documentation can be accessed at Isekai Official Website

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting
5. Commit your changes (git commit -m 'feat: add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Support

Open an issue to report problems and questions.