# fal-ai/fal architecture

> Architecture diagram of the GitHub repository fal-ai/fal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fal-ai/fal
- Repository: https://github.com/fal-ai/fal

## Overview

##### Project type and purpose
- From the file tree and README, this is a monorepo for “Fal,” a Python-based CLI + SDK toolchain that drives ML/Comfy workflows via a REST API and container runtimes.
- It contains:
- The core CLI/SDK (`projects/fal`)
- An OpenAPI-generated REST client (`projects/fal/openapi-fal-rest`)
- A separate client library package (`projects/fal_client`)
- gRPC protobuf definitions/utilities (`projects/isolate_proto`)
- Use cases: local and remote “create/deploy/run” workflows, file uploads, auth, NSFW filtering, cloud storage interactions, and container orchestration.

##### File structure
- Top-level directories: `.github` (CI), `projects/fal` (main product), `projects/fal_client` (lightweight client), `projects/isolate_proto` (protobuf schemas).
- Under `projects/fal/src/fal`:
- `cli/` – command definitions and parsers (front-end)
- `api.py`, `rest_client.py` – core HTTP client logic
- `auth/` – Auth0 vs. local auth modules
- `toolkit/` – pluggable providers (file, image, audio, video)
- `container.py` – container runtime abstractions
- `sdk.py` – high-level SDK entrypoints
- Under `openapi-fal-rest`: auto‐generated models, API stubs, and type definitions via OpenAPI.
- Under `fal_client`: a thin sync/async Python client wrapping the REST endpoints.
- Under `isolate_proto`: gRPC service definitions for an “isolate controller” (probably for sandboxed execution).

##### README for additional insights
- The README outlines commands: `fal deploy`, `fal run`, `fal create`, etc., and describes config, auth flows, and plugin points (toolkit providers).
- It probably references external services: Comfy backend, storage buckets, gRPC isolate service.

- Blue = user-facing (CLI, fal_client)
- Green = core library (SDK, toolkit)
- Orange = generated code (OpenAPI, Protobuf)
- Gray = external services (REST API, gRPC controller, Auth0, Cloud Storage)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-Facing Layer
    subgraph "User-Facing" 
        direction TB
        Fal_CLI["Fal CLI"]:::user
        Fal_Client["Fal Client Package"]:::user
    end

    %% Core SDK Layer
    subgraph "Core SDK" 
        direction TB
        Fal_SDK["Fal SDK"]:::core
        Auth_Provider["Auth Providers"]:::core
        Container_Runtime["Container Runtime"]:::core
        subgraph "Toolkit Providers" 
            direction TB
            File_Storage["File Storage Providers"]:::core
            NSFW_Filter["NSFW Filter"]:::core
            Audio_Module["Audio Toolkit"]:::core
            Video_Module["Video Toolkit"]:::core
            Utils_Module["Toolkit Utils"]:::core
        end
        Exceptions["Exception Handling"]:::core
        Logging["Logging & Tracing"]:::core
    end

    %% Codegen Layer
    subgraph "Generated Clients" 
        direction TB
        OpenAPI_Client["OpenAPI Client"]:::gen
        GRPC_Isolate["gRPC Isolate Controller"]:::gen
    end

    %% External Infrastructure
    subgraph "External Services" 
        direction TB
        REST_API["External REST API"]:::external
        GRPC_Service["Isolate Controller Service"]:::external
        Auth0["Auth0 / Local Auth Service"]:::external
        Storage["Cloud Storage (S3/GCP/R2)"]:::external
        Container["Docker / Container Runtime"]:::external
        NSFW_Service["NSFW Filter Microservice"]:::external
    end

    %% Relationships
    Fal_CLI -->|"uses"| Fal_SDK
    Fal_CLI -->|"invokes"| Fal_Client
    Fal_SDK -->|"HTTP/JSON"| OpenAPI_Client
    OpenAPI_Client -->|"requests"| REST_API
    Fal_SDK -->|"gRPC"| GRPC_Isolate
    GRPC_Isolate -->|"RPC calls"| GRPC_Service
    Fal_SDK -->|"auth calls"| Auth_Provider
    Auth_Provider -->|"OIDC / tokens"| Auth0
    Fal_SDK -->|"spawn"| Container_Runtime
    Container_Runtime -->|"docker exec"| Container
    Fal_SDK -->|"upload/download"| File_Storage
    File_Storage -->|"API calls"| Storage
    Fal_SDK -.->|"plugin"| NSFW_Filter
    NSFW_Filter -->|"local inference"| NSFW_Service
    Fal_SDK -.->|"plugin"| Audio_Module
    Fal_SDK -.->|"plugin"| Video_Module
    Fal_SDK -.->|"utilities"| Utils_Module
    Fal_SDK -->|"handles"| Exceptions
    Fal_SDK -->|"logs/traces"| Logging

    %% Click Events
    click Fal_CLI "https://github.com/fal-ai/fal/tree/main/projects/fal/src/fal/cli"
    click Fal_Client "https://github.com/fal-ai/fal/tree/main/projects/fal_client/src/fal_client"
    click Fal_SDK "https://github.com/fal-ai/fal/blob/main/projects/fal/src/fal/sdk.py"
    click Fal_SDK "https://github.com/fal-ai/fal/blob/main/projects/fal/src/fal/api.py"
    click Fal_SDK "https://github.com/fal-ai/fal/blob/main/projects/fal/src/fal/rest_client.py"
    click Fal_SDK "https://github.com/fal-ai/fal/blob/main/projects/fal/src/fal/_serialization.py"
    click OpenAPI_Client "https://github.com/fal-ai/fal/tree/main/projects/fal/openapi-fal-rest"
    click OpenAPI_Client "https://github.com/fal-ai/fal/tree/main/projects/fal/openapi-fal-rest/openapi_fal_rest"
    click GRPC_Isolate "https://github.com/fal-ai/fal/tree/main/projects/isolate_proto/src/isolate_proto"
    click Auth_Provider "https://github.com/fal-ai/fal/tree/main/projects/fal/src/fal/auth"
    click Container_Runtime "https://github.com/fal-ai/fal/blob/main/projects/fal/src/fal/container.py"
    click File_Storage "https://github.com/fal-ai/fal/tree/main/projects/fal/src/fal/toolkit/file/providers"
    click NSFW_Filter "https://github.com/fal-ai/fal/tree/main/projects/fal/src/fal/toolkit/image/nsfw_filter"
    click Audio_Module "https://github.com/fal-ai/fal/blob/main/projects/fal/src/fal/toolkit/audio/audio.py"
    click Video_Module "https://github.com/fal-ai/fal/blob/main/projects/fal/src/fal/toolkit/video/video.py"
    click Utils_Module "https://github.com/fal-ai/fal/blob/main/projects/fal/src/fal/toolkit/utils/download_utils.py"

    %% Styles
    classDef user fill:#D0E6FF,stroke:#3B7DD8,color:#0F2A5E;
    classDef core fill:#E6F7D7,stroke:#4F8F2F,color:#274E13;
    classDef gen fill:#FFECCE,stroke:#D9970E,color:#6B3B00;
    classDef external fill:#F2F2F2,stroke:#A0A0A0,color:#555555;
```
