# jtcodes/lyrictor architecture

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

- Interactive diagram: https://gitdiagram.com/jtcodes/lyrictor
- Repository: https://github.com/jtcodes/lyrictor

## Overview

Based on our analysis of both the file tree and the README, this project is a React/TypeScript web application that functions as a Final Cut Pro-inspired lyric animation editor. Its primary purpose is to let users create, sync, and animate lyrics with audio tracks. The system combines several “editor” components (timeline, lyric editor, image management including AI-generated images), authentication (login/logout flows), and project management functionality (create, edit, list projects) to offer a rich, interactive experience.

##### Main Components
- User Interface Layer – Built with React and Typescript (the entire “src” directory contains the UI code, including components for the homepage, editor, project management, authentication, etc.)
- Editor Module – This is a key component that includes:
- AudioTimeline Subsystem: Contains elements such as playback controls, timeline ruler, cursor, and text tools.
- Lyric Editing Subsystem: Consists of lyric preview components, editable text inputs, synced timeline views, and auxiliary lyric displays.
- Image Handling Subsystem: Two parts here – one for managing imported images and another for AI-driven image generation (using dedicated components and services like useAIImageService).
- Visualizer: Using Konva.js and settings tailored for audio visualization.
- Authentication Module – Components such as LogIn/LogOut buttons and login pages indicate that there is an authentication layer.
- Project Management Module – This includes creating, editing, deleting, and listing projects. It is associated with UI components for project lists and upload forms.
- API Integration – A dedicated directory (“src/api”) shows integration with Firebase for backend services.
- State Management – Usage of “zustand” for centralized state handling is clearly indicated (stores in multiple subdirectories).
- Third-Party Integrations – Technology like waveform-data, React Spectrum, and howler.js for audio functionalities.

##### Relationships and Interactions
- The Frontend UI (React components) interacts with the backend (Firebase API) for data persistence, user authentication, and project storage.
- The Editor modules communicate with their corresponding state management stores to ensure real-time updates (e.g., audio timeline, lyric preview, and visualizer settings).
- Auth and Project modules have a dependency on centralized routing and session management for user-specific data.
- The Image module splits into two interaction pathways: one for AI-generated images and another for managing locally imported ones. Each of these components interacts with its own sub-store and, in the case of AI images, likely calls out to external AI-systems or API endpoints.

##### Architectural Patterns/Design Principles
- Component-Based Architecture – Every functionality is broken into reusable React components.
- State Management via zustand – Provides easy-to-follow state containers/repositories for shared states.
- Separation of Concerns – Different directories (Auth, Editor, Project, API) encapsulate functionality. For example, timeline functions are grouped separately from lyric and image management features.
- Modularity – The use of subdirectories (like “AudioTimeline/Tools” and “Image/AI”) emphasizes encapsulation of related features.
- UI/UX Emphasis – The presence of multiple storybook configuration files and directory (.storybook) indicates a testable and reusable component library.

##### Relevant Technologies
- React + TypeScript — the core of the frontend.
- Firebase — as the backend API (authentication, project management, etc.)
- Konva.js for rendering canvas-based visualizations.
- Waveform-data and react-use-audio-player (with howler.js) for handling audio timelines.
- React Spectrum for UI components.
- Tailwind CSS for styles (tailwind.config.js).
- Storybook for component development and testing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer (React/TypeScript UI)"
        UIHome["Homepage"]:::ui
        UIAuth["Authentication Module"]:::ui
        UIEditor["Editor Module"]:::ui
        UIProjectMan["Project Management Module"]:::ui
    end

    %% Editor Module Subcomponents
    subgraph "Editor Module"
        direction TB
        ETimeline["AudioTimeline Subsystem"]:::editor
        ELyric["Lyric Editing Subsystem"]:::editor
        EImage["Image Handling Subsystem"]:::editor
            subgraph "Image Handling Subsystem"
                direction TB
                EImageAI["AI-driven Image Components"]:::editor
                EImageImported["Imported Image Management"]:::editor
            end
        EVisualizer["Visualizer"]:::editor
    end

    %% State Management Layer
    subgraph "State Management (zustand)"
        ST_Audio["AudioTimeline State"]:::state
        ST_AI["AI Image State"]:::state
        ST_Visualizer["Visualizer State"]:::state
        ST_Editor["Overall Editor State"]:::state
        ST_Project["Project State"]:::state
    end

    %% Backend/API Layer
    subgraph "Backend/API"
        Firebase["Firebase API"]:::api
    end

    %% Third-Party Integrations
    subgraph "Third-Party Integrations"
        TP_Konva["Konva.js"]:::thirdparty
        TP_Spectrum["React Spectrum"]:::thirdparty
        TP_Audio["Howler.js & Waveform-data"]:::thirdparty
    end

    %% Connections between UI Layer components
    UIHome -->|"navigates"| UIAuth
    UIHome -->|"navigates"| UIEditor
    UIHome -->|"navigates"| UIProjectMan

    %% UI Modules interacting directly with Firebase API
    UIAuth -->|"login/logout"| Firebase
    UIProjectMan -->|"CRUD_operations"| Firebase

    %% Editor Module interactions with State Management
    UIEditor -->|"sync"| ST_Editor
    ETimeline -->|"sync"| ST_Audio
    ELyric -->|"sync"| ST_Editor
    EImageAI -->|"sync"| ST_AI
    EImageImported -->|"sync"| ST_Editor
    EVisualizer -->|"sync"| ST_Visualizer

    %% State Management updating Backend
    ST_Editor -->|"save/update"| Firebase
    ST_Project -->|"project_data"| Firebase

    %% Editor Module subcomponents using Third-Party Integrations
    ETimeline -->|"audio_playback"| TP_Audio
    EVisualizer -->|"canvas_render"| TP_Konva
    UIEditor -->|"ui_components"| TP_Spectrum

    %% Click Events for UI Layer
    click UIHome "https://github.com/jtcodes/lyrictor/blob/master/src/Homepage.tsx"
    click UIAuth "https://github.com/jtcodes/lyrictor/tree/master/src/Auth/"
    click UIEditor "https://github.com/jtcodes/lyrictor/tree/master/src/Editor/"
    click UIProjectMan "https://github.com/jtcodes/lyrictor/tree/master/src/Project/"

    %% Click Events for Editor Module Subcomponents
    click ETimeline "https://github.com/jtcodes/lyrictor/tree/master/src/Editor/AudioTimeline/"
    click ELyric "https://github.com/jtcodes/lyrictor/blob/master/src/Editor/LyricEditor.tsx"
    click EImageAI "https://github.com/jtcodes/lyrictor/tree/master/src/Editor/Image/AI/"
    click EImageImported "https://github.com/jtcodes/lyrictor/tree/master/src/Editor/Image/Imported/"
    click EVisualizer "https://github.com/jtcodes/lyrictor/tree/master/src/Editor/Visualizer/"

    %% Click Events for State Management Nodes
    click ST_Audio "https://github.com/jtcodes/lyrictor/blob/master/src/Editor/AudioTimeline/store.ts"
    click ST_AI "https://github.com/jtcodes/lyrictor/blob/master/src/Editor/Image/AI/store.ts"
    click ST_Visualizer "https://github.com/jtcodes/lyrictor/blob/master/src/Editor/Visualizer/store.ts"
    click ST_Editor "https://github.com/jtcodes/lyrictor/blob/master/src/Editor/store.ts"
    click ST_Project "https://github.com/jtcodes/lyrictor/blob/master/src/Project/store.ts"

    %% Click Event for API Integration
    click Firebase "https://github.com/jtcodes/lyrictor/tree/master/src/api/"

    %% Styles
    classDef ui fill:#E0F7FA,stroke:#006064,stroke-width:2px;
    classDef editor fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef state fill:#CFD8DC,stroke:#455A64,stroke-width:2px;
    classDef api fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef thirdparty fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
```
