# render217/thullo architecture

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

- Interactive diagram: https://gitdiagram.com/render217/thullo
- Repository: https://github.com/render217/thullo

## Overview

This project is a full-stack Next.js application designed as a Trello clone (“Thullo”) for a DevChallenges submission. The system leverages modern front-end technologies (Next.js, Tailwind CSS, Shad-cn components) along with a robust backend powered by Prisma (for database management), Clerk (for authentication), Zustand (for state management), and integrations with external APIs like Unsplash and UploadThing for images and file uploads.

##### Main Components
- Frontend (User Interface & Routing):
- Located predominantly in the “src/app” folder.
- Contains separate folders for authentication ((auth)) and board functionalities ((main)/boards) that manage different views for listing boards, viewing single board details, and handling task management (kanban board interactions).

- Backend/API Layer:
- The “src/api” directory provides API endpoints handling board CRUD operations, user actions, file uploads (via uploadthing), and incoming webhooks (from Clerk).
- Next.js API routes are used, making it easy to map out HTTP endpoints which serve as the intermediary between the frontend and underlying data operations.

- Database Layer:
- Managed using Prisma with the “prisma” directory, which contains the schema and multiple migration folders.

- Third-party Services & External Integrations:
- Clerk for authentication and webhook handling, Unsplash for retrieving board cover images, and UploadThing for file uploads.
- As external entities interacting with your API layer.

- State Management and Utility Libraries:
- Utilizes Zustand (under “src/lib/store”) to manage application state (boards, cards, filters, etc.) across components.
- Utility functions and shared libraries (located in “src/lib”, “src/utils”, “src/components/ui”, etc.) support the overall functionality.

##### Relationships and Data Flows
- The Frontend renders views based on Next.js pages and calls API endpoints (located under “src/api”) for dynamic functionality such as authentication, board management, and file uploads.
- API endpoints process requests and interact with the database through Prisma, handling business logic and data persistence.
- Shared state and context (via Zustand and React Query within “src/providers”) ensure consistency across components. Illustrate how state flows from the store to various UI components.

##### Architectural Patterns to Highlight
- File System-based Routing: Next.js’s routing architecture is central, with clear distinctions between pages, layouts, and dynamic routes (notice the use of “[id]”, “[[...sign-in]]”, etc.).
- Separation of Concerns: The structure clearly divides UI components, API routes, and business logic (utils, services) to ensure a maintainable, scalable design.
- Modular Component Structure: The board components are broken down into sub-components (e.g., board card, board create form, task card details) which reinforces component reusability.

##### Final Overview
- Within the Frontend, break down key screens (Authentication, Board List, Board Detail with Kanban, etc.) and how they integrate with shared components (Navigation, Error Handling, Loaders).
- In the API/Backend layer, illustrate separate routes for boards, users, file upload, and webhooks.
- To include a visual connection between the API layer and both the database (via Prisma) and the third-party integration services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FrontendUI["Next.js Frontend (UI & Routing)"]:::frontend
        AuthViews["Authentication Views (Clerk)"]:::frontend
        BoardViews["Board Functionality Views (Boards)"]:::frontend
    end

    %% State Management
    subgraph "State Management"
        ZustandStore["State Management (Zustand)"]:::state
    end

    %% API/Backend Layer
    subgraph "API/Backend Layer"
        APIEndpoints["API Endpoints (Board CRUD, File Uploads, User Actions)"]:::backend
        BoardAPIRoutes["Board API Routes"]:::backend
        FileUploadEP["File Upload Endpoints"]:::backend
        UserAPIEP["User API Endpoints"]:::backend
        WebhookEP["Webhook Endpoints (Clerk Webhooks)"]:::backend
    end

    %% Database Layer
    subgraph "Database Layer"
        PrismaDB["Prisma/Database (Prisma ORM)"]:::database
    end

    %% External Services
    subgraph "External Services"
        ClerkService["Clerk (Authentication & Webhooks)"]:::external
        UnsplashService["Unsplash (Image Service)"]:::external
        UploadThingService["UploadThing (File Upload Service)"]:::external
    end

    %% Data Flow Connections
    FrontendUI -->|"calls"| APIEndpoints
    AuthViews -->|"auth calls"| APIEndpoints
    AuthViews -->|"integrates"| ClerkService
    BoardViews -->|"board operations"| APIEndpoints
    BoardViews -->|"retrieves images"| UnsplashService
    FrontendUI -->|"updates state"| ZustandStore
    AuthViews -->|"updates state"| ZustandStore
    BoardViews -->|"updates state"| ZustandStore

    APIEndpoints -->|"delegates to"| BoardAPIRoutes
    APIEndpoints -->|"delegates to"| FileUploadEP
    APIEndpoints -->|"delegates to"| UserAPIEP
    APIEndpoints -->|"delegates to"| WebhookEP
    APIEndpoints -->|"queries"| PrismaDB
    BoardAPIRoutes -->|"reads/writes"| PrismaDB
    UserAPIEP -->|"reads/writes"| PrismaDB

    FileUploadEP -->|"calls"| UploadThingService
    WebhookEP -->|"receives events from"| ClerkService

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef backend fill:#FFC0CB,stroke:#000,stroke-width:1px;
    classDef database fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef external fill:#FFFF99,stroke:#000,stroke-width:1px;
    classDef state fill:#D3D3D3,stroke:#000,stroke-width:1px;

    %% Click Events
    click FrontendUI "https://github.com/render217/thullo/tree/main/src/app"
    click AuthViews "https://github.com/render217/thullo/tree/main/src/app/(auth)"
    click BoardViews "https://github.com/render217/thullo/tree/main/src/app/(main)/boards"
    click APIEndpoints "https://github.com/render217/thullo/tree/main/src/app/api"
    click BoardAPIRoutes "https://github.com/render217/thullo/tree/main/src/app/api/boards"
    click FileUploadEP "https://github.com/render217/thullo/tree/main/src/app/api/uploadthing"
    click UserAPIEP "https://github.com/render217/thullo/tree/main/src/app/api/users"
    click WebhookEP "https://github.com/render217/thullo/blob/main/src/app/api/webhooks/clerk/route.ts"
    click PrismaDB "https://github.com/render217/thullo/tree/main/prisma"
    click ZustandStore "https://github.com/render217/thullo/tree/main/src/lib/store"
    click UnsplashService "https://github.com/render217/thullo/blob/main/src/utils/functions/getUnsplashImage.ts"
    click UnsplashService "https://github.com/render217/thullo/blob/main/src/lib/store/useUnsplashImage.ts"
```
