# petrsovadina/table-gen-ai architecture

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

- Interactive diagram: https://gitdiagram.com/petrsovadina/table-gen-ai
- Repository: https://github.com/petrsovadina/table-gen-ai

## Overview

##### Main System Components
- Frontend (Client): This is primarily handled by Next.js. It resides in the “app” folder (with pages for authentication, dashboard, etc.) and utilizes many UI components located within “components” (including UI element libraries, file uploaders, table viewers, prompt managers, etc.). Global styling, Tailwind configurations, and providers for themes and Supabase are also part of this layer.
- AI Integration: The system leverages Anthropic Claude for data generation. Although details of the integration are abstracted, one can assume API calls in “lib/anthropic.ts” and related utility modules tie the business logic to this external AI service.
- Database & Persistence: The “supabase” folder (with migration scripts) and “lib/supabase.ts” represent integration with Supabase for data storage (likely including user data, generated tables, and versioned data).
- Utility & Helper Modules: Files in “utils” (e.g., for CSV export, data processing, encryption) capture core business logic for handling file data, processing, and validation.
- State Management & Testing: The “store” directory leverages state management for table data, and testing directories (Jest and Cypress tests) imply quality assurance for both unit and end-to-end tests.

##### Elaborate on Relationships and Interactions
- The User Interface (browser client) interacts with the backend endpoints through HTTP requests (AJAX/fetch) for actions like authentication, file uploads, data generation, and exports.
- Once the client uploads a CSV/Excel file, file processing is triggered in the frontend, then the data is sent to the API routes.
- The API routes work with helper libraries (in “utils” and “lib”) to validate and process the data, then make calls to the external Anthropic Claude AI service (via “lib/anthropic.ts”) to generate the missing data.
- Processed results are stored or versioned in the Supabase database.
- The UI components for tables, forms, and prompts then render updated data, all handled through React components and state management (using “store/tableStore.ts” and “store/useStore.ts”).

##### Architectural Patterns and Design Principles
- Full-Stack Separation: There is a clear separation between the UI layer, server-side API endpoints, and the integrated external services.
- Modularization: The project is highly modular with components, utilities, and API endpoints separated into distinct directories to promote maintainability and scalability.
- Serverless/Edge-optimized Functions: API routes and middleware indicate an architecture optimized for serverless or edge deployment patterns.
- External Integration Abstraction: The external AI service (Anthropic Claude) is encapsulated within dedicated modules, making testing and future changes easier.
- Responsive and Accessible UI with Theming: Components for dark mode and responsive design ensure a good client experience.

##### Final Touches
- Every component’s role is clearly defined.
- Data flow (upload → processing → generation → storage → display).
- Review the project’s modular architecture: each subfolder (app, components, lib, utils, supabase) reflects a defined layer or service.
- Clarity and comprehensiveness rather than overcomplicating details.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "User Layer"
        UB["User Browser"]:::external
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE1["Next.js Pages"]:::frontend
        FE2["UI Components"]:::frontend
    end

    %% Server/API Layer
    subgraph "Server/API Layer"
        BE1["Auth API"]:::backend
        BE2["Data Generation API"]:::backend
        BE3["Data Export API"]:::backend
        BE4["Middleware"]:::backend
    end

    %% Utilities & Helpers
    subgraph "Utilities & Helpers"
        UT1["CSV Export Utility"]:::utils
        UT2["Data Processing Utility"]:::utils
        UT3["Data Validation Utility"]:::utils
        UT4["Encryption Utility"]:::utils
        UT5["General Utilities"]:::utils
        UT6["AI Data Generation Utility"]:::utils
    end

    %% State Management
    subgraph "State Management"
        ST1["Table Store"]:::state
        ST2["UI Store"]:::state
    end

    %% External Integration
    subgraph "External Integration"
        AI["AI Service (Anthropic Claude)"]:::external
    end

    %% Database Layer
    subgraph "Database Layer"
        DB["Supabase DB"]:::db
    end

    %% Testing
    subgraph "Testing"
        TE1["Component Testing"]:::test
        TE2["Utility Testing"]:::test
        TE3["E2E Testing"]:::test
    end

    %% Data Flow
    UB --> FE1
    UB --> FE2

    FE1 -->|"HTTP"| BE1
    FE1 -->|"HTTP"| BE2
    FE1 -->|"HTTP"| BE3

    FE2 -->|"state update"| ST1
    FE2 -->|"state update"| ST2

    %% API to Middleware (pre-processing)
    BE4 -.-> BE1
    BE4 -.-> BE2
    BE4 -.-> BE3

    %% API using Utilities
    BE2 -->|"util_call"| UT5
    BE3 -->|"export"| UT1

    %% AI Integration flow
    BE2 -->|"ai_util"| UT6
    UT6 -->|"generate"| AI

    %% API interactions with Database
    BE1 -->|"db_ops"| DB
    BE2 -->|"db_ops"| DB
    BE3 -->|"db_ops"| DB

    %% Testing links
    TE1 --> FE2
    TE2 --> UT1
    TE3 --> FE1

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef backend fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef external fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef db fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef utils fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef state fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
    classDef test fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;

    %% Click Events
    click FE1 "https://github.com/petrsovadina/table-gen-ai/tree/main/app"
    click FE2 "https://github.com/petrsovadina/table-gen-ai/tree/main/components"
    click BE1 "https://github.com/petrsovadina/table-gen-ai/tree/main/app/api/auth"
    click BE2 "https://github.com/petrsovadina/table-gen-ai/tree/main/app/api/generate"
    click BE3 "https://github.com/petrsovadina/table-gen-ai/tree/main/app/api/export"
    click BE4 "https://github.com/petrsovadina/table-gen-ai/blob/main/middleware.ts"
    click AI "https://github.com/petrsovadina/table-gen-ai/blob/main/lib/anthropic.ts"
    click UT1 "https://github.com/petrsovadina/table-gen-ai/blob/main/utils/csvExport.ts"
    click UT2 "https://github.com/petrsovadina/table-gen-ai/blob/main/utils/dataProcessing.ts"
    click UT3 "https://github.com/petrsovadina/table-gen-ai/blob/main/utils/dataValidation.ts"
    click UT4 "https://github.com/petrsovadina/table-gen-ai/blob/main/utils/encryption.ts"
    click UT5 "https://github.com/petrsovadina/table-gen-ai/blob/main/lib/utils.ts"
    click UT6 "https://github.com/petrsovadina/table-gen-ai/blob/main/utils/aiDataGeneration.ts"
    click ST1 "https://github.com/petrsovadina/table-gen-ai/blob/main/store/tableStore.ts"
    click ST2 "https://github.com/petrsovadina/table-gen-ai/blob/main/store/useStore.ts"
    click DB "https://github.com/petrsovadina/table-gen-ai/tree/main/supabase"
    click TE1 "https://github.com/petrsovadina/table-gen-ai/blob/main/tests/components/AIGenerator.test.tsx"
    click TE2 "https://github.com/petrsovadina/table-gen-ai/blob/main/tests/utils/csvExport.test.ts"
    click TE3 "https://github.com/petrsovadina/table-gen-ai/blob/main/cypress/e2e/table_operations.cy.js"
```
