# vibeflowing-inc/vibe_figma architecture

> Architecture diagram of the GitHub repository vibeflowing-inc/vibe_figma, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vibeflowing-inc/vibe_figma
- Repository: https://github.com/vibeflowing-inc/vibe_figma

## Overview

##### Project type and purpose
- VibeFigma is primarily a developer tool—a converter that transforms Figma designs into production-ready React/TypeScript components with Tailwind CSS.
- It ships both as a CLI (local, interactive or scripted) and as a REST API server, exposing the same core conversion engine over HTTP.

##### File structure
- Top-level artifacts:
- bin/vibefigma.js → executable CLI entrypoint
- Dockerfile, bun.lock, package.json → environment & build configuration
- docs/API.md → REST API documentation
- src/cli → CLI commands, prompts, logging, file-writer utilities
- src/core → core conversion logic subdivided into:
– cleaner (AI-backed code cleanup prompt)
– css-to-tailwind (mappings, converters, utilities)
– figma (Figma API client, JSX/HTML transformations)
- src/middleware → request validation & security for the API server
- src/config, src/utils → shared config & helper functions
- README.md → high-level usage, features, and architecture hints

##### README for additional insights
- Confirms two usage modes: “npx vibefigma” CLI and REST API server (POST /v1/api/vibe-figma).
- Describes third-party integrations: Figma API, optional Google Generative AI for cleanup.
- Mentions configurability through environment variables and CLI flags.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Inputs
    subgraph "User Interfaces" 
        direction TB
        UserCLI["User (CLI)"]:::frontend
        UserHTTP["Client (HTTP)"]:::frontend
    end

    %% CLI Layer
    subgraph "CLI Interface" 
        direction TB
        CLIExec["CLI Executable"]:::frontend
        CLIBootstrap["CLI Bootstrap"]:::frontend
        ConvertCmd["Convert Command"]:::frontend
        CLIUtils["CLI Utilities"]:::frontend
        FileWriter["File Writer"]:::infra
        Logger["Logger"]:::infra
        Prompts["Prompts"]:::infra
    end

    %% API Layer
    subgraph "REST API Server"
        direction TB
        RESTEndpoint["REST Endpoint /v1/api/vibe-figma"]:::frontend
        Validation["Validation Middleware"]:::frontend
        Security["Security Middleware"]:::frontend
        APIDocs["API Documentation"]:::external
    end

    %% Core Conversion Engine
    subgraph "Core Conversion Engine"
        direction TB

        subgraph "Figma Extraction & Transformation"
            direction TB
            FigmaClient["Figma API Client"]:::core
            FigmaToHTML["Figma → HTML/JSX"]:::core
            FigmaToTailwind["Figma → Tailwind"]:::core
            TransformJSX["JSX AST Transformer"]:::core
            ReactWrapper["React JSX Wrapper"]:::core
            FigmaTypes["Figma Types"]:::core
            ComponentName["Component Name Util"]:::core
        end

        subgraph "CSS-to-Tailwind Converter"
            direction TB
            MainConverter["Main Converter"]:::core
            TailwindConverter["Tailwind Converter"]:::core
            NodesManager["Tailwind Nodes Manager"]:::core
            MappingsDir["Mappings Directory"]:::core
            DeclMap["declaration-converters-mapping.ts"]:::core
            MediaMap["media-params-mapping.ts"]:::core
            PseudosMap["pseudos-mapping.ts"]:::core
            UtilsMap["utilities-mapping.ts"]:::core
            CSSConverterTypes["Converter Types"]:::core
            CSSUtils["Converter Utilities"]:::core
        end

        subgraph "AI Code Cleaner (Optional)"
            direction TB
            AICleaner["AI Cleaner Orchestrator"]:::core
            AIPrompt["Cleanup Prompt Template"]:::core
        end
    end

    %% Shared Config & Utils
    subgraph "Shared Config & Utils"
        direction TB
        EnvConfig["Environment Config"]:::infra
        Helpers["Helper Functions"]:::infra
    end

    %% External Services & Infrastructure
    subgraph "External Services & Infrastructure"
        direction TB
        FigmaAPI["Figma REST API"]:::external
        GoogleAI["Google Generative AI"]:::external
        FileSystem["File System / Artifact Store"]:::infra
    end

    %% Interactions
    UserCLI --> CLIExec
    CLIExec --> CLIBootstrap
    CLIBootstrap --> ConvertCmd
    ConvertCmd --> MainConverter
    ConvertCmd --> FileWriter
    ConvertCmd --> Prompts
    ConvertCmd --> Logger

    UserHTTP --> RESTEndpoint
    RESTEndpoint --> Validation
    Validation --> Security
    Security --> MainConverter

    MainConverter --> FigmaClient
    FigmaClient --> FigmaAPI
    FigmaClient --> FigmaToHTML
    FigmaToHTML --> FigmaToTailwind
    FigmaToTailwind --> TransformJSX
    TransformJSX --> ReactWrapper
    ReactWrapper --> FileWriter
    ReactWrapper --> FileSystem

    MainConverter --> TailwindConverter
    TailwindConverter --> NodesManager
    NodesManager --> MappingsDir
    MappingsDir --> DeclMap
    MappingsDir --> MediaMap
    MappingsDir --> PseudosMap
    MappingsDir --> UtilsMap
    TailwindConverter --> CSSConverterTypes
    TailwindConverter --> CSSUtils

    AICleaner --> AIPrompt
    AICleaner --> GoogleAI
    AICleaner --> FileWriter

    EnvConfig --> CLIBootstrap
    EnvConfig --> RESTEndpoint
    Helpers --> ConvertCmd
    Helpers --> MainConverter

    %% Documentation
    APIDocs

    %% Click Events
    click CLIExec "https://github.com/vibeflowing-inc/vibe_figma/blob/main/bin/vibefigma.js"
    click CLIBootstrap "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/cli/index.ts"
    click ConvertCmd "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/cli/commands/convert.ts"
    click FileWriter "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/cli/utils/file-writer.ts"
    click Logger "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/cli/utils/logger.ts"
    click Prompts "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/cli/utils/prompts.ts"
    click RESTEndpoint "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/index.ts"
    click Validation "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/middleware/validation.ts"
    click Security "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/middleware/security.ts"
    click APIDocs "https://github.com/vibeflowing-inc/vibe_figma/blob/main/docs/API.md"
    click FigmaClient "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/core/figma/figma-client.ts"
    click FigmaToHTML "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/core/figma/figma-to-html.ts"
    click FigmaToTailwind "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/core/figma/figma-to-tailwind.ts"
    click TransformJSX "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/core/figma/transform-jsx.ts"
    click ReactWrapper "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/core/figma/figma-react.ts"
    click FigmaTypes "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/core/figma/types.ts"
    click ComponentName "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/core/figma/utils/component-name.ts"
    click MainConverter "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/core/css-to-tailwind/index.ts"
    click TailwindConverter "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/core/css-to-tailwind/tailwind-converter.ts"
    click NodesManager "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/core/css-to-tailwind/tailwind-nodes-manager.ts"
    click MappingsDir "https://github.com/vibeflowing-inc/vibe_figma/tree/main/src/core/css-to-tailwind/mappings"
    click DeclMap "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/core/css-to-tailwind/mappings/declaration-converters-mapping.ts"
    click MediaMap "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/core/css-to-tailwind/mappings/media-params-mapping.ts"
    click PseudosMap "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/core/css-to-tailwind/mappings/pseudos-mapping.ts"
    click UtilsMap "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/core/css-to-tailwind/mappings/utilities-mapping.ts"
    click CSSConverterTypes "https://github.com/vibeflowing-inc/vibe_figma/tree/main/src/core/css-to-tailwind/types"
    click CSSUtils "https://github.com/vibeflowing-inc/vibe_figma/tree/main/src/core/css-to-tailwind/utils"
    click AICleaner "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/core/cleaner/index.ts"
    click AIPrompt "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/core/cleaner/prompt.txt"
    click EnvConfig "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/config/env.ts"
    click Helpers "https://github.com/vibeflowing-inc/vibe_figma/blob/main/src/utils/helpers.ts"
    click FileSystem "https://github.com/vibeflowing-inc/vibe_figma/blob/main/README.md"
    click FileSystem "https://github.com/vibeflowing-inc/vibe_figma/blob/main/.env.example"

    %% Styles
    classDef frontend fill:#9f6,stroke:#333,stroke-width:1px
    classDef core fill:#6cf,stroke:#333,stroke-width:1px
    classDef external fill:#f96,stroke:#333,stroke-width:1px
    classDef infra fill:#ccc,stroke:#333,stroke-width:1px
```
