# imaimai17468/kirinuki-playlist architecture

> Architecture diagram of the GitHub repository imaimai17468/kirinuki-playlist, 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/imaimai17468/kirinuki-playlist
- Repository: https://github.com/imaimai17468/kirinuki-playlist

## Overview

##### Project Overview & Type
- This is a full-stack application designed for cutting YouTube videos and creating custom playlists.
- The frontend part is built with Next.js (with SSR & CSR capabilities) using modern UI libraries (React, Tailwind CSS, Shadcn UI).
- The backend is implemented with Hono (a lightweight web framework) running at the edge and integrated into the Next.js app.
- The system relies on Drizzle ORM for database interactions and uses Cloudflare D1 (and optionally a local libsql-server) for actual or local development databases.
- It also incorporates testing using Bun and a dependency injection design for modular, easily testable components.

##### Project File Structure
- Top-level directories include:
- src/components: Contains various UI components grouped by features and layout.
- src/db: Contains database configurations (under config), data models, and services that access these models.
- src/repositories: Contains repository patterns and data access layers encapsulating database operations along with hooks to interface with the services.
- Other directories (hooks, libs) support shared code and utilities.
- Additional project artifacts include:
- Drizzle and drizzle/meta directories: Contain SQL migration files and snapshots used for database schema management.
- Configuration files for Next.js (next.config.mjs), Drizzle, Tailwind, and Git hooks.
- CI/CD and linting configuration files are also present to support development best practices.

##### Main Components
A. Frontend Components:
- Next.js Pages & Layouts (src/app, src/components/layout, src/components/ui, etc.)
- UI components and React hooks (src/components, src/hooks) that handle user interface rendering and state.
- API Client Singleton: Implements a consistent way to call backend APIs, as indicated by the README’s note on API client management.
B. Backend Components:
- Hono API Endpoints: Represented by the files in src/app/api/[...route] (videos.ts, playlists.ts, authors.ts, route.ts) acting as the interface for external API calls.
- Dependency Injection in the service layer: Each service (in src/db/services) is created via factory functions (e.g., create*Service) that inject necessary dependencies like the database client.
C. Database:
- Drizzle ORM Configuration and Migration: Present in drizzle/ and drizzle.config.ts for schema evolution and database connection.
- Database Models & Services: Under src/db/models and src/db/services, which encapsulate data definitions and business logic.
- Repository Layer: Under src/repositories managing data access with testable, isolated units.
D. External Services & Deployment:
- Cloudflare D1 for production database deployment.
- Testing and local DB setups using Docker/libsql-server handled by scripts (scripts/migrate.ts, scripts/seed.ts).
- Edge Runtime for API endpoints and Cloudflare Pages for deployment.
E. Development Tools:
- Bun as the runtime and package manager.
- Biome and Lefthook for code quality and Git hook management.

##### Relationships & Interactions
- Frontend interacts with backend API endpoints through the API client.
- Hono API endpoints depend on the dependency-injected service layer that encapsulates business logic.
- Services communicate with the database via Drizzle ORM and through the repository abstraction.
- Testing frameworks and utilities ensure that each layer (especially data repositories) can operate with mocked or in-memory databases.

##### Architectural Patterns to Highlight
- Separation of Concerns: Distinguish between presentation (Next.js pages/UI), business logic (Hono API endpoints and backend services), and data access (repositories, Drizzle ORM).
- Dependency Injection: Emphasized in the service layer for improved modularity and testability.
- Singleton API Client Pattern: For managing and centralizing API calls in the frontend.
- Repository Pattern: For abstracting data access and ensuring testability and separation from direct database calls.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FP1["Next.js Pages (src/app)"]
        FP2["Layout Components (src/components/layout)"]
        FP3["UI Components (src/components)"]
        FP4["React Hooks (src/hooks)"]
        FP5["API Client Singleton (.cursor/rules/frontend-api-client.mdc)"]
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BE1["Hono API Endpoints (src/app/api/[...route])"]
        BE2["Hono DI Config (src/db/config/hono)"]
        BE3["Service Layer (src/db/services)"]
    end

    %% Database Layer
    subgraph "Database Layer"
        DB1["Drizzle ORM Config (drizzle.config.ts)"]
        DB2["SQL Migrations (drizzle/)"]
        DB3["Schema Snapshots (drizzle/meta/)"]
        DB4["Database Models (src/db/models)"]
        DB5["Repository Layer (src/repositories)"]
    end

    %% External Services
    subgraph "External Services"
        EX1["Cloudflare D1 / Local DB (Cloudflare D1 / Libsql-server)"]
        EX2["Migration & Seeding Scripts (scripts/migrate.ts, scripts/seed.ts)"]
    end

    %% Development Tools
    subgraph "Development Tools"
        DT1["Bun Runtime (bun.lockb, bunfig.toml)"]
        DT2["Biome Tooling (biome.json)"]
        DT3["Git Hooks (lefthook.yml, .husky)"]
    end

    %% Frontend Connections
    FP1 -->|"initiates"| FP5
    FP3 -->|"triggers"| FP5
    FP4 -->|"supports"| FP5

    %% Frontend to Backend
    FP5 -->|"calls"| BE1

    %% Backend Connections
    BE2 -->|"injects"| BE3
    BE1 -->|"delegates"| BE3

    %% Backend to Database
    BE3 -->|"queries"| DB5
    BE3 -->|"uses"| DB4

    %% Database Internal Connections
    DB4 -->|"configuredBy"| DB1
    DB1 -->|"applies"| DB2
    DB2 -->|"captures"| DB3
    DB5 -->|"accesses"| EX1

    %% External Services Connection
    EX2 -->|"setsUp"| EX1

    %% Class definitions for colors
    classDef frontend fill:#ACE,stroke:#333,stroke-width:1px;
    classDef backend fill:#CFC,stroke:#333,stroke-width:1px;
    classDef database fill:#FCE,stroke:#333,stroke-width:1px;
    classDef external fill:#F9C,stroke:#333,stroke-width:1px;
    classDef devtools fill:#EDF,stroke:#333,stroke-width:1px;

    class FP1,FP2,FP3,FP4,FP5 frontend;
    class BE1,BE2,BE3 backend;
    class DB1,DB2,DB3,DB4,DB5 database;
    class EX1,EX2 external;
    class DT1,DT2,DT3 devtools;

    %% Click Events for Frontend
    click FP1 "https://github.com/imaimai17468/kirinuki-playlist/tree/main/src/app"
    click FP2 "https://github.com/imaimai17468/kirinuki-playlist/tree/main/src/components/layout"
    click FP3 "https://github.com/imaimai17468/kirinuki-playlist/tree/main/src/components"
    click FP4 "https://github.com/imaimai17468/kirinuki-playlist/tree/main/src/hooks"
    click FP5 "https://github.com/imaimai17468/kirinuki-playlist/blob/main/.cursor/rules/frontend-api-client.mdc"

    %% Click Events for Backend
    click BE1 "https://github.com/imaimai17468/kirinuki-playlist/blob/main/src/app/api/[...route]"
    click BE2 "https://github.com/imaimai17468/kirinuki-playlist/tree/main/src/db/config/hono"
    click BE3 "https://github.com/imaimai17468/kirinuki-playlist/tree/main/src/db/services"

    %% Click Events for Database
    click DB1 "https://github.com/imaimai17468/kirinuki-playlist/blob/main/drizzle.config.ts"
    click DB2 "https://github.com/imaimai17468/kirinuki-playlist/tree/main/drizzle/"
    click DB3 "https://github.com/imaimai17468/kirinuki-playlist/tree/main/drizzle/meta/"
    click DB4 "https://github.com/imaimai17468/kirinuki-playlist/tree/main/src/db/models"
    click DB5 "https://github.com/imaimai17468/kirinuki-playlist/tree/main/src/repositories"

    %% Click Events for External Services
    click EX2 "https://github.com/imaimai17468/kirinuki-playlist/blob/main/scripts/migrate.ts"
    click EX2 "https://github.com/imaimai17468/kirinuki-playlist/blob/main/scripts/seed.ts"

    %% Click Events for Development Tools
    click DT1 "https://github.com/imaimai17468/kirinuki-playlist/blob/main/bun.lockb"
    click DT2 "https://github.com/imaimai17468/kirinuki-playlist/blob/main/biome.json"
    click DT3 "https://github.com/imaimai17468/kirinuki-playlist/blob/main/lefthook.yml"
```
