# ephibbs/flowtoken architecture

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

- Interactive diagram: https://gitdiagram.com/ephibbs/flowtoken
- Repository: https://github.com/ephibbs/flowtoken

## Overview

##### Project type and purpose
- FlowToken is a front-end React component library (published as an npm package) whose sole purpose is to animate streaming text (and other inline content) from Large Language Models (LLMs). It provides a set of highly customizable, performant, CSS-based animations for words, characters, code blocks, images, and even user-supplied custom components.

##### File structure
- Top level:
- package.json, tsconfig.json, tailwind.config.js, postcss.config.js, eslint/ignore files → build, lint & distribution configuration
- .storybook/ → Storybook integration for live component preview & docs
- stories/ → sample/demo code for each component in Storybook
- src/
- src/index.ts → library entry point (exports)
- src/components/ → the actual React components:
– AnimatedMarkdown.tsx
– AnimatedText.tsx
– AnimatedImage.tsx
– CodeRenderer.tsx & DefaultCode.tsx
– SplitText.tsx
- src/utils/animations.ts → centralized definitions of CSS keyframes and utility helpers
- src/styles.css → base CSS (animation class names, utility classes)
- This is purely a UI-centric, component-based codebase—no backend, no database, no external microservices.

##### README for additional insights
- Confirms React + optional Tailwind usage
- Emphasizes streaming of LLM content, markdown support, custom component injection
- Lists all built-in animation types (fadeIn, dropIn, typewriter, etc.)

##### Main components & their relationships
- AnimatedMarkdown
- Parses markdown → splits into inline tokens → delegates rendering to SplitText, CodeRenderer, and/or customComponents
- SplitText
- Receives plain text or markdown node → splits by word/char based on “sep” prop → wraps each chunk in AnimatedText
- AnimatedText
- Applies a given CSS animation class (e.g. “fadeIn”) with duration & timing props → renders a span per chunk
- CodeRenderer & DefaultCode
- Syntax-highlight code blocks (using a highlighter library) and animate appearance
- AnimatedImage
- Renders images with entry animations
- utils/animations.ts
- Central registry of @keyframes and helper functions → imported by components or included in styles
- src/index.ts
- Exposes all components & CSS entrypoint (styles.css) as the package API

##### Important architectural patterns & principles
- Component composition & single responsibility: each component wraps one concern (markdown → split → animate)
- Strategy pattern via customComponents prop: consumers can inject their own renderers at parse-time
- CSS-first animations: leverages pure CSS @keyframes for smooth GPU-accelerated effects
- Configuration & theming via props + tailwind integration

- Orange for “Consumer App” and “Storybook”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Consumers
    ConsumerApp["Consumer App"]:::external
    Storybook["Storybook"]:::external

    %% Package Boundary
    subgraph "FlowToken (npm package)"
        direction TB
        Index["src/index.ts"]:::entry

        subgraph "React Components"
            direction TB
            AM["AnimatedMarkdown"]:::react
            ST["SplitText"]:::react
            AT["AnimatedText"]:::react
            CR["CodeRenderer"]:::react
            DC["DefaultCode"]:::react
            AI["AnimatedImage"]:::react
        end

        subgraph "Utilities & Styles"
            direction TB
            Anim["animations.ts"]:::util
            Styles["styles.css"]:::util
        end
    end

    %% Relationships
    ConsumerApp -->|"imports FlowToken API"| Index
    Storybook -->|"imports FlowToken API"| Index

    Index -->|"exports component"| AM
    Index -->|"exports component"| ST
    Index -->|"exports component"| AT
    Index -->|"exports component"| CR
    Index -->|"exports component"| DC
    Index -->|"exports component"| AI

    AM -->|"parses markdown delegates"| ST
    AM -->|"parses markdown delegates"| CR
    ST -->|"splits text→chunks"| AT
    CR -->|"syntax-highlights animates"| DC

    AT -->|"uses animation classes"| Styles
    AI -->|"uses animation classes"| Styles

    AT -->|"uses keyframes/helpers"| Anim
    CR -->|"uses keyframes/helpers"| Anim
    AI -->|"uses keyframes/helpers"| Anim

    %% Click Events
    click Index "https://github.com/ephibbs/flowtoken/blob/main/src/index.ts"
    click AM "https://github.com/ephibbs/flowtoken/blob/main/src/components/AnimatedMarkdown.tsx"
    click ST "https://github.com/ephibbs/flowtoken/blob/main/src/components/SplitText.tsx"
    click AT "https://github.com/ephibbs/flowtoken/blob/main/src/components/AnimatedText.tsx"
    click CR "https://github.com/ephibbs/flowtoken/blob/main/src/components/CodeRenderer.tsx"
    click DC "https://github.com/ephibbs/flowtoken/blob/main/src/components/DefaultCode.tsx"
    click AI "https://github.com/ephibbs/flowtoken/blob/main/src/components/AnimatedImage.tsx"
    click Anim "https://github.com/ephibbs/flowtoken/blob/main/src/utils/animations.ts"
    click Styles "https://github.com/ephibbs/flowtoken/blob/main/src/styles.css"
    click Storybook "https://github.com/ephibbs/flowtoken/blob/main/.storybook/main.ts"
    click Storybook "https://github.com/ephibbs/flowtoken/blob/main/.storybook/preview.ts"
    click Controls "https://github.com/ephibbs/flowtoken/blob/main/stories/Controls.tsx"
    click ExampleCustom "https://github.com/ephibbs/flowtoken/blob/main/stories/ExampleCustomComponent.tsx"
    click MarkdownStories "https://github.com/ephibbs/flowtoken/blob/main/stories/Markdown.stories.tsx"
    click RandomSender "https://github.com/ephibbs/flowtoken/blob/main/stories/RandomMarkdownSender.tsx"
    click TestMarkdown "https://github.com/ephibbs/flowtoken/blob/main/stories/TestMarkdown.ts"
    click TextStories "https://github.com/ephibbs/flowtoken/blob/main/stories/Text.stories.tsx"
    click TailwindCSS "https://github.com/ephibbs/flowtoken/blob/main/stories/tailwind.css"

    %% Styles
    classDef react fill:#e0f7ff,stroke:#00bfff
    classDef util fill:#e6ffe6,stroke:#00cc00
    classDef external fill:#ffe6cc,stroke:#ff8c00
    classDef entry fill:#f0e6ff,stroke:#bf00ff
```
