Architecture Overview¶
Repository layout¶
alchemy/
alc/ Core library — models, services, path system, cookbook, plugins
app/ FastAPI web application — the studio dashboard
cloud/ Cloud control plane (accounts, Lambda)
dev/ Development utilities and manifests
docs/ This documentation
tests/ Test suite
The core library — alc/¶
alc/models/ — domain model layer¶
The canonical home for all Pydantic models describing production entities.
Nothing outside this package defines domain models. Services and plugins
import from here; the __init__.py is the public API (from alc.models import X).
| Area | Contents |
|---|---|
task.py |
TaskManifest — the manufacturing state of a single task |
version.py |
VersionManifest, VersionPointer, VersionStatus, UserVersions |
media.py |
MediaReference — standardized media/path pointer |
project.py |
Project, Company, AlchemyConfig |
script/ |
Screenplay domain (ScriptModel, ScriptScene, ScriptBlock, ...) |
character/ |
Character domain (voices, wardrobe, design) |
camera/ |
Camera domain |
edit/ |
Editorial domain (SceneTimeline, DialogueClip, ...) |
alc/path/ — addressing system¶
PathObject is the foundational infrastructure: every file
path in production is a structured address, not a raw string.
alc/file/ — filesystem domain¶
Models that describe how files behave, not just what they are. AlcFile
is polymorphic — .load() returns the correct concrete subclass by extension.
AlcImage handles EXR (oiiotool), PSD (psd-tools), and standard raster formats.
Sequence handles image-sequence scanning, frame ranges, and ffmpeg commands.
alc/services/ — execution layer¶
Business logic and external integrations. Services operate on models; they
don't define them. Highlights: task_msd.py (MSD_SERVICE), project.py
(PROJECT_REGISTRY), selection.py (SelectionManager / POM),
deadline/ (render farm), media/ (video, voice, sequences), ai/
(external AI providers as services).
alc/cookbook/ — recipe system¶
The automation engine. Recipes are CI/CD for creative work, triggered at task phase boundaries.
alc/plugins/ — software bridges¶
One directory per software package, each exposing the same create / edit / query contract so Alchemy can automate any software with a Python backend.
alc/agents/ — agent framework¶
Micro-agent infrastructure. Each agent operates within the bounds of a
RecipeStep — it knows its goal, its pass/fail criteria, and its context
(the PathObject of the current task).
The web app — app/¶
The studio dashboard: FastAPI + Jinja2 + HTMX + Tailwind.
Layering rules¶
- Domain models live in
alc/models/only. - Service-local request/response shapes stay in their service directory.
- Plugins define no models — they import from
alc.models. CFG = AlchemyConfig().load()— singleton config, loaded once at startup.POM = SelectionManager()— active PathObject, synced by every route.- Missing registry entities are hard errors, never silent defaults.
Naming conventions¶
| Pattern | Example |
|---|---|
| Entity ID | 010_0010 (shot), maya (software) |
| Task ID | project_episode_entityType_parent_group_child_task |
| Version | 008.001 (major.minor) |
| Disk path | {root}/{company}/{project}/PUBLISHES/{tree}/{entity_type}/{parent}/{child}/{task}/... |
| MSD path | PUBLISHES/msd/{task_id}.json |
| Web token | /project/{project_id}/{entity_type}/{parent}/{child}/task/{task_code}/versions |
Technology stack¶
| Layer | Technology |
|---|---|
| Domain models | Pydantic v2 |
| Web framework | FastAPI + Uvicorn |
| Templates / reactivity | Jinja2 + HTMX |
| Styling | Tailwind CSS |
| Real-time | WebSockets |
| Image processing | Pillow, oiiotool, psd-tools |
| Render farm | Deadline (Thinkbox) |
| Version control | Perforce |
| Production tracking | ShotGrid / Flow |
| Editorial | OpenTimelineIO |