# zeitgg/betterflare architecture

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

- Interactive diagram: https://gitdiagram.com/zeitgg/betterflare
- Repository: https://github.com/zeitgg/betterflare

## Overview

##### Project’s Role and Purpose
- BetterFlare is a full-stack web application focused on managing Cloudflare R2 storage. Its purpose is to provide an intuitive and modern UI that allows users to manage storage buckets (and objects within) hosted on Cloudflare R2.
- It leverages Next.js for its frontend, and tRPC for a type-safe API layer. Additionally, state management is handled by Zustand, and it uses a modern UI component framework (shadcn/ui with Tailwind CSS).

##### Break Down the File Structure to Discover Architectural Components
- The “src/app” folder includes pages and API endpoints, showing standard Next.js routing with specific subdirectories for dashboard, settings, and onboarding.
- The “src/app/api/trpc” folder holds the API endpoints specific to tRPC, whereas “src/server/routers” and “src/server/services” indicate that there is a server layer that abstracts business logic (e.g., the r2Service) and routes.
- The “src/components” folder (with many UI component files in “src/components/ui”) and “src/hooks”, “src/store” directories indicate a valuable separation between UI logic, custom hooks, and state management.
- Configuration files (like next.config.ts, tsconfig.json, package.json) confirm the project’s use of Next.js, TypeScript, and modern build/development setups.

##### Main Components
a. Frontend (Client Side):
- Next.js Pages and Layouts: Represented by pages like the home (src/app/page.tsx), dashboard (src/app/dashboard/page.tsx), and settings (src/app/settings/page.tsx).
- UI Components: All the reusable UI components under “src/components/ui” as well as dashboard-specific components and the onboarding flow.
- State Management Layer: Include the Zustand store (e.g., bucketStore.ts, credentialsStore.ts) which manages client-side state such as user credentials and current bucket selections.
- API Providers: The tRPC provider component and client code ("src/trpc/client.ts", "src/trpc/provider.tsx") illustrate the integration layer between the frontend and backend APIs.

b. API / Backend Layer:
- tRPC Endpoints: The API routes defined in “src/app/api/trpc” and the server’s tRPC integration (src/server/trpc.ts) form the backbone of the type-safe communication between client and server.
- Server Routers and Services: The routers (e.g., “src/server/routers/r2Router.ts”) and services (e.g., “src/server/services/r2Service.ts”) handle processing requests, business logic, and interfacing with Cloudflare R2 (with some AWS S3 SDK compatibility) for bucket and object operations.

c. External Dependencies/Integrations:
- Cloudflare R2: As the external cloud storage service that the app interacts with.
- AWS S3 SDK: Utilized for compatibility, so incorporate this connection as a bridge to Cloudflare R2.

##### Relationships and Interactions
- A user interacts with the Frontend UI where input (such as credentials or bucket management actions) is handled.
- The state management layer (Zustand) keeps track of session information like Cloudflare credentials.
- Actions on the UI trigger API calls via the tRPC client, passing requests to the backend.
- The tRPC router on the server routes the requests to appropriate service layers (e.g., r2Service) that interact with Cloudflare R2 (via the AWS S3 SDK) to fetch, update, or delete storage buckets or objects.
- Results or responses flow back in the same process, enabling the UI to update accordingly.

##### Architectural Patterns Highlighted
- Separation of Concerns: Clear distinction between frontend presentation (Next.js UI, components, state), API routing (tRPC endpoints), and service abstraction (server services interacting with Cloudflare R2).
- Modularization: Each component (pages, components, hooks, services) is organized in its own directory, ensuring maintainability and easy traceability.
- Type-Safe Communication: Through the consistent use of tRPC across the client and server ensures robust type safety end-to-end.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    U("User"):::user

    %% Client (Frontend) Layer
    subgraph "Client (Frontend)"
        subgraph "Pages & Layouts"
            Home["Home Page (Next.js)"]:::frontend
            Dashboard["Dashboard Page (Next.js)"]:::frontend
            Settings["Settings Page (Next.js)"]:::frontend
            Bucket["Bucket Page (dynamic)"]:::frontend
        end
        subgraph "UI Components"
            Reusable["Reusable UI Components<br>(shadcn/ui)"]:::frontend
            DashboardUI["Dashboard Specific Components"]:::frontend
            Onboarding["Onboarding Flow Component"]:::frontend
            Theme["Global Theme Provider"]:::frontend
        end
        subgraph "State Management"
            BucketStore["Bucket State Store"]:::frontend
            CredentialsStore["Credentials Store"]:::frontend
        end
        subgraph "API Providers"
            TRPC_ClientSetup["tRPC Client Setup"]:::frontend
            TRPC_Provider["tRPC Provider Component"]:::frontend
        end
    end

    %% API (Backend) Layer
    subgraph "API (Backend)"
        TRPC_Endpoints["tRPC Endpoints (Next.js API)"]:::backend
        TRPC_Server["tRPC Integration (Server)"]:::backend
        Routers["Cloudflare R2 Router"]:::backend
        Services["Cloudflare R2 Service"]:::backend
    end

    %% External Services
    subgraph "External Services"
        Cloudflare["Cloudflare R2"]:::external
        AWSS3["AWS S3 SDK"]:::external
    end

    %% Connections from User to Client
    U -->|"interacts"| Home
    U --> Dashboard
    U --> Settings
    U --> Bucket

    %% Pages interacting with other client components
    Home -->|"renders"| Reusable
    Dashboard -->|"renders"| DashboardUI
    Settings -->|"applies"| Theme
    Bucket -->|"updates state via"| BucketStore
    Bucket --> CredentialsStore
    Dashboard -->|"calls API"| TRPC_Provider
    Home -->|"manages state"| CredentialsStore

    %% API Providers linking to API Layer
    TRPC_Provider -->|"sendsReq"| TRPC_Endpoints
    TRPC_ClientSetup -->|"configures"| TRPC_Provider

    %% API Flow within Backend Layer
    TRPC_Endpoints -->|"forwards"| TRPC_Server
    TRPC_Server -->|"routes"| Routers
    Routers -->|"invokes"| Services
    Services -->|"calls"| Cloudflare
    Services -->|"calls"| AWSS3
    Cloudflare -->|"returns"| Services
    AWSS3 -->|"returns"| Services
    Services -->|"response"| Routers
    Routers -->|"response"| TRPC_Server
    TRPC_Server -->|"response"| TRPC_Endpoints
    TRPC_Endpoints -->|"response"| TRPC_Provider

    %% Click Events for Next.js Pages & Layouts
    click Home "https://github.com/zeitgg/betterflare/blob/master/src/app/page.tsx"
    click Dashboard "https://github.com/zeitgg/betterflare/blob/master/src/app/dashboard/page.tsx"
    click Settings "https://github.com/zeitgg/betterflare/blob/master/src/app/settings/page.tsx"
    click Bucket "https://github.com/zeitgg/betterflare/blob/master/src/app/dashboard/bucket/[name]/page.tsx"

    %% Click Events for UI Components
    click Reusable "https://github.com/zeitgg/betterflare/tree/master/src/components/ui"
    click DashboardUI "https://github.com/zeitgg/betterflare/tree/master/src/components/dashboard"
    click Onboarding "https://github.com/zeitgg/betterflare/blob/master/src/components/onboarding-flow.tsx"
    click Theme "https://github.com/zeitgg/betterflare/blob/master/src/components/theme-provider.tsx"

    %% Click Events for State Management
    click BucketStore "https://github.com/zeitgg/betterflare/blob/master/src/store/bucketStore.ts"
    click CredentialsStore "https://github.com/zeitgg/betterflare/blob/master/src/store/credentialsStore.ts"

    %% Click Events for API Providers
    click TRPC_ClientSetup "https://github.com/zeitgg/betterflare/blob/master/src/trpc/client.ts"
    click TRPC_Provider "https://github.com/zeitgg/betterflare/blob/master/src/trpc/provider.tsx"

    %% Click Events for tRPC API Endpoints
    click TRPC_Endpoints "https://github.com/zeitgg/betterflare/tree/master/src/app/api/trpc"

    %% Click Events for Backend Integration
    click TRPC_Server "https://github.com/zeitgg/betterflare/blob/master/src/server/trpc.ts"
    click Routers "https://github.com/zeitgg/betterflare/blob/master/src/server/routers/r2Router.ts"
    click Services "https://github.com/zeitgg/betterflare/blob/master/src/server/services/r2Service.ts"

    %% Styles
    classDef user fill:#f9e79f,stroke:#000,stroke-width:2px;
    classDef frontend fill:#cce5ff,stroke:#0056b3,stroke-width:2px;
    classDef backend fill:#d5f5e3,stroke:#28a745,stroke-width:2px;
    classDef external fill:#fdfd96,stroke:#ff9800,stroke-width:2px;
```
