artcraft-services README

The project's README from github.com/storytold/artcraft-services. As one markdown file: README.md.

ArtCraft Services

This repository contains ArtCraft's backend, HTTP API, background workers, and web frontends. It is a Rust and TypeScript monorepo with shared API definitions, provider clients, database queries, and development tooling.

The Tauri desktop application is maintained in storytold/artcraft, along with the product overview, feature demos, and desktop downloads.

Backend architecture

storyteller-web is the main HTTP service, built with Rust, Actix Web, and Tokio. It handles authentication, accounts, media uploads and libraries, generation requests, job status, credits, and Stripe billing. The service retains the storyteller-web name, and its hosted API uses https://api.storyteller.ai.

Generation spans the HTTP service, provider integrations, and asynchronous workers:

flowchart LR
  Clients[Web, desktop, and API clients] --> API[storyteller-web]
  API --> Router[artcraft_router]
  Router --> Providers[Generation providers]
  Providers -->|Webhooks| API
  Workers[Background workers] -->|Poll jobs| Providers
  API --> DB[(MySQL)]
  Workers --> DB
  API --> Storage[(Object storage)]
  Workers --> Storage

A typical generation request follows this path:

  1. The API authenticates the caller, validates the request and input media, and checks the user's access and credits.
  2. The generation pipeline calculates the cost, bills the wallet, and uses artcraft_router to build and submit a provider-specific request. The API records inference jobs in MySQL and returns job tokens to the client.
  3. Completion is handled through provider webhooks or polling workers, depending on the integration. Results are downloaded into object storage, registered as media files, and associated with the completed jobs. Separate workers handle follow-up processing such as video thumbnails.
  4. Clients poll job-status endpoints and load the resulting media through CDN URLs.

Storage responsibilities are split across these components:

Component Role
MySQL + SQLx Accounts, media metadata, inference jobs, wallets, and bills
Redis Caching, rate limiting, and job progress
Elasticsearch Search indexes and queries
S3-compatible storage / R2 Uploaded media, generated assets, and derived files

HTTP routes and handlers live in storyteller_web/src/http_server. MySQL queries belong in the shared mysql_queries crate so that handlers, workers, and CLI tools use the same data access layer. Reusable billing components live under crates/service/plugins, and background services live under crates/service/job.

HTTP API

The API exposes two generation interfaces:

For example, a programmatic video request goes to POST /v1/omni_api/generate/video. The response contains an inference_job_token, which the caller polls with GET /v1/omni_api/job_status/job/{token}. The Omni API guide covers authentication, request and response bodies, URL inputs, and runnable examples.

Start with these sources when adding or tracing an endpoint:

Frontend

frontend contains the Nx workspace for React and TypeScript apps and shared libraries. The main web frontends use Vite, with Zustand and signals for state, Three.js for 3D scenes, and shared UI and generation tools.

Path Purpose
frontend/apps/artcraft-webapp Browser application at app.getartcraft.com
frontend/apps/artcraft-website-next Product website at getartcraft.com (Next.js)
frontend/libs/api HTTP clients, API host selection, and models
frontend/libs/omni-gen Shared generation logic
frontend/libs/components Reusable UI, editors, and generation controls
frontend/libs/tauri-api Frontend bindings for native desktop commands

The web apps call the backend through the shared API library, which handles JSON and multipart requests and session credentials. Libraries such as tauri-api and tauri-utils remain because shared web components still import their types, helpers, and browser-compatible behavior. The native desktop app and libraries used only by that app live in the separate desktop repository.

Repository layout

artcraft-services/
├── crates/
│   ├── service/web/       # HTTP services, including storyteller_web
│   ├── service/job/       # Provider workers, media processing, analytics
│   ├── service/plugins/   # Shared billing and service components
│   ├── api_clients/       # ArtCraft API types, clients, router, provider clients
│   ├── schema/            # Database access, public tokens/enums, bucket paths
│   ├── lib/               # Shared Rust utilities
│   └── cli/               # Development and operations tools
├── frontend/
│   ├── apps/              # Web frontends
│   └── libs/              # Shared TypeScript libraries
├── _database/             # SQL migrations, materialized schemas, search schemas
├── _docs/                 # Setup guides and technical documentation
├── _tools/postman/        # HTTP request collections
├── build/                 # Service Dockerfiles
├── script/                # Development, build, and database tooling
└── Cargo.toml             # Rust workspace

Local development

Use Rust/Cargo for backend work and Node.js/npm for the main frontend workspace. See the development setup guide for toolchain setup and frontend README for dependency installation and Nx usage.

Backend

The server needs a migrated MySQL database, Redis, Elasticsearch configuration, object storage, and credentials for the integrations being exercised. The server setup guide covers local MySQL and Redis; the remaining configuration is defined in the server config directory and startup code.

In development, the server loads storyteller-web.common.env, storyteller-web.development.env, and storyteller-web.development-secrets.env from its configuration search paths: the repository root, ./config, and the server's config directory. Its bootstrap skips the root .env file.

With the toolchain and service configuration in place, run from the repository root:

SQLX_OFFLINE=true cargo check -p storyteller-web
SQLX_OFFLINE=true cargo run -p storyteller-web

The default bind address is 0.0.0.0:12345, configurable through BIND_ADDRESS. GET /_status exposes the service health check. Provider polling and thumbnail processing require their corresponding worker processes and configuration.

SQLX_OFFLINE=true uses the checked-in .sqlx query metadata during compilation; the running server still needs its databases. When changing SQLx queries, use script/rust/sqlx_codegen_database.sh to regenerate metadata against migrated development databases.

Web frontend

To run the browser app against a local backend:

cd frontend
npm install
VITE_USE_LOCAL_API=true npx nx dev artcraft-webapp

The browser app runs at http://localhost:4201. VITE_USE_LOCAL_API=true selects http://localhost:12345; without that override, its Vite development proxy targets the hosted API. API host selection lives in StorytellerApiHostStore.

From frontend, build the web app with npx nx build artcraft-webapp. The product website is a standalone Next.js app (not part of the Nx workspace); run it from the repository root with ./script/website/unix_frontend_website_dev.sh.

The website runs at http://localhost:3000. Repository-root launchers are in script/website. For desktop development, use the ArtCraft desktop repository.

Further reading

artcraft-services (storytold/artcraft-services)

monorepo
Searching Database…

1.2K ·GitHub
Artcraft-services
What is this?This is the backend, HTTP API, background workers, and web frontends for ArtCraft, an AI generation platform that creates images, video, audio, meshes, and splats.
Is this the whole ArtCraft app, or just the backend and web parts?Just the backend and web side. The Tauri desktop app, its product overview, demos, and downloads live in the separate storytold/artcraft repository.
How do I run the backend and web frontend locally?Run the backend from the repository root once its services are configured (it binds to 0.0.0.0:12345 by default); for the web app, run it against a local or hosted API via VITE_USE_LOCAL_API, then build it from the frontend workspace with 'npx nx build artcraft-webapp'.
What do I need installed before touching the backend?Rust/Cargo for the backend and Node.js/npm for the Nx frontend workspace, plus a migrated MySQL database, Redis, Elasticsearch, and S3-compatible object storage.
Can I just call the generation API with any account?The session-based app endpoints work for any logged-in user, but the programmatic '/v1/omniapi' key-based endpoints require API access to be explicitly enabled on the account.
What does a generation request actually do behind the scenes?The API authenticates the caller, checks credits, calculates cost and bills the wallet, then uses the artcraft-router crate to submit a provider-specific job; results land in object storage and get polled via job-status endpoints or provider webhooks.
How is data split across the different storage systems?MySQL (via SQLx) holds accounts, media metadata, jobs, wallets and bills; Redis handles caching, rate limiting and job progress; Elasticsearch powers search; S3-compatible storage/R2 holds uploaded and generated media.
What frontend stack powers the web apps?An Nx workspace of React/TypeScript apps built with Vite, using Zustand and signals for state and Three.js for 3D scenes, including 'artcraft-webapp' (app.getartcraft.com) and a separate Next.js marketing site (getartcraft.com).
Is billing integrated into the generation flow?Yes, generation requests debit a credit wallet and the service integrates Stripe for billing alongside accounts, media libraries, and job status tracking.
What are similar projects?waoowaoo, printfilm, os, walgit, gin-vue-admin, whirl, open-higgsfield, polar
Which topics is it in?object-storage, billing, stripe, elasticsearch, s3, threejs, tauri, monorepo, vite, mysql, video-generation, 3d
Creator
storytold
Size
1.3 GB
Stars
1.2K
Updated
CommitOct 16
Age
1mo
Commits · 90 Days