app¶

The studio dashboard. See Web App for the concepts. Route modules are numerous and change often — this page documents the stable spine.

Bootstrap¶

app.main ¶

Context builders¶

app.context ¶

AlcContextMiddleware ¶

AlcContextMiddleware(app)

Pure ASGI middleware (NOT BaseHTTPMiddleware — streaming responses must render inside the bound context) that:

activates the alc request context for /c/{company_id}[/project/{pid}] URLs so every model-layer path lookup grounds to the URL, and
307-redirects legacy /project/..., /ide/..., /upload/... URLs to the owning company's /c/{cid}/... equivalent (method + body preserved).

Source code in app\context.py

def __init__(self, app):
    self.app = app

default_company_id ¶

default_company_id(request: Request) -> str

The company a context-less request should ground to: this browser's remembered choice (cookie) if still valid, else the global boot default. Read-only — never writes config.

Source code in app\context.py

def default_company_id(request: Request) -> str:
    """The company a context-less request should ground to: this browser's
    remembered choice (cookie) if still valid, else the global boot default.
    Read-only — never writes config."""
    cid = request.cookies.get(ACTIVE_COMPANY_COOKIE)
    if cid and cid in CFG.companies:
        return cid
    return CFG.company_id

default_project_id ¶

default_project_id(
    request: Request, company_id: str
) -> str | None

This browser's remembered project for company_id (cookie) if it still exists on that company, else the company's last-known project. Read-only.

Source code in app\context.py

def default_project_id(request: Request, company_id: str) -> str | None:
    """This browser's remembered project for *company_id* (cookie) if it still
    exists on that company, else the company's last-known project. Read-only."""
    company = CFG.companies.get(company_id)
    if not company:
        return None
    pid = request.cookies.get(ACTIVE_PROJECT_COOKIE)
    if pid and pid in (company.projects or {}):
        return pid
    return company.last_project_id

company_prefix ¶

company_prefix() -> str

The canonical URL prefix for the ACTIVE company (/c/{company_id}). Request-scoped inside a request; the persisted default elsewhere. Shared by python URL builders and (via template_helpers) every Jinja template.

Source code in app\context.py

def company_prefix() -> str:
    """The canonical URL prefix for the ACTIVE company (``/c/{company_id}``).
    Request-scoped inside a request; the persisted default elsewhere. Shared by
    python URL builders and (via template_helpers) every Jinja template."""
    cid = alc_context.active_company_id() or CFG.company_id
    return f"/c/{cid}"

accessible_companies ¶

accessible_companies() -> dict

CFG.companies filtered to what the current identity may see: org-linked companies need membership, unlinked local companies stay open.

Source code in app\context.py

def accessible_companies() -> dict:
    """CFG.companies filtered to what the current identity may see: org-linked
    companies need membership, unlinked local companies stay open."""
    ids = IDENTITY.accessible_company_ids()
    if ids is None:
        return CFG.companies
    return {cid: c for cid, c in CFG.companies.items() if cid in ids}

get_deadline_context ¶

get_deadline_context(request: Request) -> dict

Reads render state from app.state — no circular imports needed.

Source code in app\context.py

def get_deadline_context(request: Request) -> dict:
    """Reads render state from app.state — no circular imports needed."""
    manager = request.app.state.render_manager
    return {
        "progress": manager.progress_percent,
        "pending_jobs": manager.pending_jobs,
        "pending_count": manager.pending_count,
        "rendering_count": manager.rendering_count,
        "done_today": manager.completed_today_count or 0,
        "has_errors": manager.has_errors,
    }

get_dashboard_context ¶

get_dashboard_context(
    request: Request, project_id: str | None = None
) -> dict

Standard studio context for every page.

Pure READ: grounded by the request's URL context (AlcContextMiddleware), never syncs POM or writes config. Two tabs on different companies each get their own context.

Source code in app\context.py

def get_dashboard_context(request: Request, project_id: str | None = None) -> dict:
    """
    Standard studio context for every page.

    Pure READ: grounded by the request's URL context (AlcContextMiddleware),
    never syncs POM or writes config. Two tabs on different companies each get
    their own context.
    """
    company = alc_context.active_company()
    projects = company.projects if company else {}
    current_project_id = project_id or alc_context.active_project_id()
    current_project = projects.get(current_project_id) if current_project_id else None
    deadline = get_deadline_context(request)

    current_path = ""
    counts = {
        "scenes": 0,
        "videos": 0,
        "characters": 0,
        "props": 0,
        "dressing": 0,
        "environments": 0,
    }
    has_script = False
    if current_project is not None:
        try:
            current_path = Path(current_project.path_object.path).as_posix()
        except Exception:
            current_path = ""
        try:
            active_registry = PROJECT_REGISTRY.get_project(
                current_project_id, company_id=company.id if company else None
            )
            has_script = active_registry.has_script
            from alc.services.videos import list_videos

            counts = {
                "scenes": active_registry.scene_count,
                "videos": len(list_videos(current_project_id)),
                "characters": active_registry.character_count,
                "props": active_registry.prop_count,
                "dressing": active_registry.dressing_count,
                "environments": active_registry.environment_count,
            }
        except Exception as e:
            logger.error(f"Failed to fetch registry counts: {e}")

    identity = IDENTITY.peek()
    view_mode = resolve_view_mode(request, identity, company)

    # The persistent Unreal connection header (shell) reads this. Only loaded in
    # the Unreal lens so no other workspace pays for the disk read.
    unreal_session = None
    if view_mode == "unreal" and company and current_project_id:
        from alc.services import unreal as unreal_svc

        unreal_session = unreal_svc.load_session(
            getattr(company, "perforce_root", None), company.id, current_project_id
        )

    return {
        "request": request,
        "projects": projects,
        "current_project": current_project,
        "companies": accessible_companies(),
        "current_company": company,
        "identity": identity,
        "unreal_session": unreal_session,
        **nav_context(view_mode),
        "counts": counts,
        "has_script": has_script,
        "project_id": current_project_id,
        "company_id": company.id if company else None,
        "current_path_debug": current_path,
        **deadline,  # spreads progress, active_count, rendering_count, done_today, has_errors
    }

resolve_asset_code ¶

resolve_asset_code(asset_type: str) -> str | None

Maps any variant of an asset type label to its 3-letter code.

Source code in app\context.py

def resolve_asset_code(asset_type: str) -> str | None:
    """Maps any variant of an asset type label to its 3-letter code."""
    return ASSET_TYPE_MAP.get(asset_type)

Workspace (view-mode) + sidebar navigation registry.

A workspace is a function, not a role: "what am I here to do?" — work my tasks, browse the project, plan it, or read the dashboard. It controls WHAT shows up in the production sidebar (and eventually per-workspace landing pages), never what a user is allowed to do. Roles (WorkOS admin/member) come in later only to pick a sensible DEFAULT workspace and, eventually, which workspaces are offered — anyone can switch from the header, and the choice persists per-browser in a cookie.

Add workspaces or retag items here; templates render from this registry and need no edits.

ToolPath(
    path: str,
    scope: str = "project",
    label: str = "",
    icon: str = "",
)

Where a sidebar tool lives, for deep-link restore.

path is the tool's canonical sub-path relative to its scope root: for a project tool everything after /c/{cid}/project/{pid}/; for a company tool everything after /c/{cid}/. scope selects which. Matching is segment-prefixed — an incoming URL belongs to this tool when its sub-path equals path or extends it on a segment boundary, so a deep view like scenes/010/read still restores the Scenes tool and its lens.

label and icon are the tool's human identity — the name and Font Awesome glyph the sidebar shows. Carried here so a page can be REFERENCED as data (e.g. a walkthrough step that links to "the My Tasks page" and has Alchemy confirm it) instead of every referrer re-typing the label. label falls back to a title-cased id; icon to a generic page glyph.

page_catalog() -> list[tuple[str, 'ToolPath']]

(nav_id, ToolPath) for every linkable Alchemy page, in sidebar order — the set a walkthrough step may point at. Ordered by the sidebar SECTIONS so the picker reads top-to-bottom the way the app does; anything not in a section trails at the end.