FaceForge

A local-first, self-hosted Asset Management System (AMS) focused on entities (real or fictional, human or non-human) and the assets related to them.

Project maintained by h8rt3rmin8r Hosted on GitHub Pages — Theme by mattgraham

FaceForge

FaceForge

A local-first, self-hosted Asset Management System (AMS) focused on entities (real or fictional, human or non-human) and the assets attached to them.

FaceForge is designed to be a stable, integration-friendly “boring core” for storing metadata + files, while advanced features (recognition, graph visualization, training, third-party integrations) live in optional plugins.

Status

This repository is currently docs-first scaffolding with an initial runnable Core implementation:

If you’re arriving here to understand the project, start with:

What FaceForge is (and isn’t)

FaceForge is:

FaceForge is not (in Core):

Those capabilities are intended to ship as plugins that talk to Core over its public APIs.

Audience

For End Users

FaceForge is a self-hosted application designed to run locally on your machine. You do not need to write code or run commands to use it.

  1. Download: Go to GitHub Releases. You will see two main assets:
    • FaceForge Desktop Installer (.exe or .msi): This is the recommended download for most users. It includes the full Desktop App, the Core API server, and everything you need to run FaceForge.
    • FaceForge Core API (.zip): This is an advanced package containing only the Python API server (Core). Use this only if you intend to run the API headlessly or integrate it into a custom setup without the Desktop UI.
  2. Install & Setup: Follow the User Guide.
    • On first launch, the System Settings screen will ask you to select a Data Directory (default: C:\FaceForge).
    • The Desktop app manages the background services (database, API, storage) for you.
  3. Use: Managing your assets happens in the Web UI, which you launch from the Desktop app.

For Developers

This repository is a monorepo containing the Core service (Python) and the Desktop orchestrator (Rust/Tauri).

High-level architecture (intended)

Core conventions (from the spec)

When implementation starts, the repo will follow these conventions:

Repository layout

Quick map of what lives where:

  desktop/      # Tauri desktop shell (Sprint 12 MVP)
faceforge/
  core/         # FastAPI Core service (runnable today)
  desktop/      # Tauri desktop shell
  docs/         # Project spec + MVP sprint plan (source of truth)
  scripts/      # Dev scripts (PowerShell) to run/check Core using .venv
  brand/        # Logos, favicon, fonts (UI branding assets)

Core service code is a standard Python package under:

core/
  src/faceforge_core/       # app entrypoint + API + DB + storage
    app.py                  # FastAPI app factory / wiring
    api/v1/                 # versioned HTTP routes
    db/                     # SQLite schema + migrations + queries
    internal/               # internal CLIs/utilities (dev/admin)
  tests/                    # pytest tests for Core
  pyproject.toml            # Core packaging/deps

If you’re new and wondering “where do I add a route?”, start at:

Getting started (Development)

FaceForge Core is runnable in dev today, and FaceForge Desktop can orchestrate it.

Prerequisites

Before you start, make sure these tools are installed.

If you have multiple Pythons installed, ensure python resolves to 3.12.x in the same terminal where you run ./scripts/*.ps1.

Run Desktop (dev)

Prereq: Rust toolchain (stable).

From the repo root:

What it does:

Notes:

Run Core (dev)

From the repo root (Windows PowerShell):

Prereq: Python 3.12.x installed (used only to bootstrap the repo-local .venv).

Then open:

Core also serves a lightweight Web UI (no runtime Node dependency):

Core now exposes initial Entities + Assets v1 endpoints (token required):

Core also exposes initial Jobs endpoints (Sprint 9):

Core also exposes initial Descriptor + Field Definition endpoints (Sprint 7):

Core also exposes initial Relationships endpoints (Sprint 8):

Core also exposes initial Plugins endpoints:

Plugins

Core discovers plugin manifests from:

Minimal plugin.json example:

{
  "id": "demo.plugin",
  "name": "Demo Plugin",
  "version": "0.1.0",
  "capabilities": ["ui"],
  "config_schema": {
    "type": "object",
    "properties": {
      "example_flag": { "type": "boolean" }
    },
    "additionalProperties": true
  }
}

Notes:

For optional SeaweedFS/S3 storage configuration (Sprint 6), see:

Auth

Core binds to localhost by default and requires a per-install token for non-health endpoints.

Build a Windows executable (Core)

To produce a standalone faceforge-core.exe (PyInstaller one-file build):

  1. Verify Python is available (3.12.x):
    • python --version
  2. Build the executable from the repo root:
    • ./scripts/build-core.ps1
    • This script creates/updates the repo-local .venv, installs build dependencies, and runs PyInstaller.
    • If it fails to delete core/dist or core/build, close any terminals/Explorer windows using those folders and re-run.
      • Optional: ./scripts/build-core.ps1 -AllowTimestampFallback

Outputs:

Run the built executable (example):

Notes:

If you want to run Core in dev instead of building an exe:

GitHub Releases

This repo includes a GitHub Actions workflow that builds and attaches release assets automatically.

How to cut a release (GitHub UI):

  1. Go to Releases → Draft a new release.
  2. Pick an existing tag or create a new one (recommended tag format: v0.1.0).
  3. Fill in title/notes and click Publish release.
  4. Wait for the release-core workflow to finish; it will upload assets onto the Release.

After the workflow completes, the Release will contain:

The token is generated on first start (if missing) and stored in:

Send it using either header:

For the Web UI in a browser, you can also log in at /ui/login, which stores the token in an HttpOnly cookie.

Example (PowerShell):

Checks (format + lint + tests)

These scripts create/use the repo-local .venv and always run commands through it.

To get productive right now:

Building for Release

To create a distributable installer:

  1. Build Core Executable: 
    ./scripts/build-core.ps1

    This uses PyInstaller to freeze the Python service into core/dist/faceforge-core.exe.

  2. Build Desktop Bundle: 
      ./scripts/build-desktop.ps1
  # or, if you want to run Tauri directly:
  Push-Location 'desktop/src-tauri'
  cargo tauri build
  Pop-Location

    This packages the Desktop shell, bundles the Core executable (as a sidecar), and includes necessary tools (ExifTool, etc.).

Contributing

Contributions are welcome, especially as the repo moves from docs → scaffolding → MVP.

License

See LICENSE.