# jakubjirous/trancify architecture

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

- Interactive diagram: https://gitdiagram.com/jakubjirous/trancify
- Repository: https://github.com/jakubjirous/trancify

## Overview

##### Project Type & Purpose
- Trancify is a full-stack web application serving as a trance and progressive music player. It provides functionalities like track playback, playlist management, metadata editing, and search, along with rich media features via the Media Session API.
- The tech stack includes Next.js (v15), React (v19), Tailwind CSS, and UI libraries (Shadcn UI, Radix UI) on the front end. On the backend, it leverages Supabase for database services and Prisma for database handling, with migration scripts and query/mutation actions in the project.

##### Analyzing the File Structure
- The top-level files (e.g., next.config.mjs, package.json, tsconfig.json) and configuration files (e.g., tailwind.config.ts, vercel.json) indicate web app configuration and deployment settings.
- The src folder is key, especially the new Next.js App Router structure under src/app, which contains layouts, pages, and domain-specific routes (e.g., /playlist/[id], /playlists, /tracks).
- The components directory is well-organized into subfolders by domain (e.g., now-playing, player, playlist, sidebar, tracks). Each folder contains reusable UI components.
- Other directories like lib (actions, db, queries, mutations), hooks, providers, config, and utils demonstrate clear separation of concerns: handling business logic, database migrations, and UI state and behavior.
- The db folder (with Prisma schema, migrations, seed scripts) confirms that the application leverages a relational database structured and managed via Prisma and Supabase.

##### Main Components
- Client/Browser: Represent the end-user’s web browser that interacts with Trancify.
- Frontend Application:
- Next.js Application (the primary “View” layer) that contains:
- Routing & Pages (from the src/app folder with layouts, page components, dynamic routes for playlists and tracks)
- UI Components (from the src/components folder – player, sidebar, now-playing, etc.)
- Providers & Hooks (global state management and shared behavior)
- Backend/API Layer:
- API Endpoints/Server-side interactions that are interwoven with Next.js (if using server-side rendering or API routes)
- Database Operations Layer (via src/lib/db with migrations, queries, and mutations) which encapsulates business logic for CRUD on playlists and tracks.
- Database & External Services:
- Supabase (as the database as well as potentially authentication provider)
- Prisma (ORM layer, handling the schema and migrations)

##### Relationships and Data Flow
- User → Browser → Next.js Frontend.
- Within the frontend, differentiate between:
- UI Components (displaying player controls, playlists, track data)
- Hooks/Providers that manage application state (global context, keyboard navigation, player controls).

##### Architectural Patterns & Technologies
- Next.js “App Router” structure: emphasize separation of layout and page components.
- Component-based design: note how UI components are organized by feature (player, playlist, now-playing, sidebar).
- Clear separation between UI (presentation) and business logic (actions, database operations).
- Use of hooks and providers for handling state and cross-cutting concerns.
- Incorporation of third-party libraries (Tailwind CSS for styling, Shadcn UI / Radix UI for controls) – these can be noted near the frontend section.
- Database abstraction using Prisma with migration and query scripts indicating a solid schema evolution and data management process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User"]:::user
    B["Browser"]:::client
    U -->|"request"| B

    subgraph "Frontend Application (Next.js)"
        FR["Routing & Pages"]:::frontend
        subgraph "UI Components"
            PL["Player Module"]:::component
            NP["Now Playing Module"]:::component
            PM["Playlist Management"]:::component
            SS["Sidebar & Search"]:::component
            TD["Tracks Display"]:::component
        end
        P["Providers"]:::provider
        H["Hooks"]:::provider
        FR -->|"renders"| PL
        FR -->|"renders"| NP
        FR -->|"renders"| PM
        FR -->|"renders"| SS
        FR -->|"renders"| TD
        FR -->|"utilizes"| P
        FR -->|"utilizes"| H
    end

    subgraph "Backend/API Layer"
        ALA["Business Logic Actions"]:::backend
        DB["Database Operations (Supabase & Prisma)"]:::database
        ALA -->|"queries/mutations"| DB
    end

    B -->|"UIEvents"| FR
    PL -->|"callsActions"| ALA
    NP -->|"callsActions"| ALA
    PM -->|"callsActions"| ALA
    SS -->|"callsActions"| ALA
    TD -->|"callsActions"| ALA
    FR -->|"APICalls"| ALA

    style U fill:#cce5ff,stroke:#333,stroke-width:2px
    style B fill:#cce5ff,stroke:#333,stroke-width:2px
    style FR fill:#ffcccb,stroke:#333,stroke-width:2px
    style PL fill:#cfffcf,stroke:#333,stroke-width:2px
    style NP fill:#cfffcf,stroke:#333,stroke-width:2px
    style PM fill:#cfffcf,stroke:#333,stroke-width:2px
    style SS fill:#cfffcf,stroke:#333,stroke-width:2px
    style TD fill:#cfffcf,stroke:#333,stroke-width:2px
    style P fill:#f6e58d,stroke:#333,stroke-width:2px
    style H fill:#f6e58d,stroke:#333,stroke-width:2px
    style ALA fill:#d1c4e9,stroke:#333,stroke-width:2px
    style DB fill:#ffeeba,stroke:#333,stroke-width:2px,stroke-dasharray: 5,5

    click FR "https://github.com/jakubjirous/trancify/tree/main/src/app/(root)"
    click PL "https://github.com/jakubjirous/trancify/tree/main/src/components/player"
    click NP "https://github.com/jakubjirous/trancify/tree/main/src/components/now-playing"
    click PM "https://github.com/jakubjirous/trancify/tree/main/src/components/playlist"
    click SS "https://github.com/jakubjirous/trancify/tree/main/src/components/sidebar"
    click TD "https://github.com/jakubjirous/trancify/tree/main/src/components/tracks"
    click P "https://github.com/jakubjirous/trancify/tree/main/src/providers"
    click H "https://github.com/jakubjirous/trancify/tree/main/src/hooks"
    click DB "https://github.com/jakubjirous/trancify/tree/main/src/lib/db"
    click ALA "https://github.com/jakubjirous/trancify/tree/main/src/lib/actions"

classDef user fill:#cce5ff,stroke:#333,stroke-width:2px;
classDef client fill:#cce5ff,stroke:#333,stroke-width:2px;
classDef frontend fill:#ffcccb,stroke:#333,stroke-width:2px;
classDef component fill:#cfffcf,stroke:#333,stroke-width:2px;
classDef provider fill:#f6e58d,stroke:#333,stroke-width:2px;
classDef backend fill:#d1c4e9,stroke:#333,stroke-width:2px;
classDef database fill:#ffeeba,stroke:#333,stroke-width:2px,stroke-dasharray: 5,5;
```
