# haishanh/cherry architecture

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

- Interactive diagram: https://gitdiagram.com/haishanh/cherry
- Repository: https://github.com/haishanh/cherry

## Overview

##### Main System Components

a) Frontend Layer:
- SvelteKit application (evident from the src/routes structure)
- Component library (src/lib/components)
- Client-side stores (src/lib/client/*.store.ts)

b) Backend Layer:
- API Routes (src/routes/api/*)
- Service Layer (src/lib/server/services)
- Database Layer (src/lib/server/db)

c) Authentication System:
- Multiple auth providers support (src/routes/api/auth/[provider])
- User management (src/lib/server/services/user.service.ts)

d) External Services:
- S3 integration (s3.service.ts)
- Favicon fetching service
- OIDC providers

**[Client Browser] ←→ [Frontend Layer (SvelteKit)] ←→ [API Layer] ←→ [Service Layer] ←→ [Database]**
- ↑
- ↓
- [External Services]

##### Component Details

Frontend Layer (Blue):
- Main routes (/bookmarks, /tags, /groups, /settings)
- Component hierarchy
- Stores for state management

API Layer (Green):
- Endpoints by function:
- Authentication endpoints
- Bookmark management
- Tag management
- Management
- Admin operations
- Import/Export functionality

Service Layer (Yellow):
- BookmarkService
- TagService
- GroupService
- UserService
- ImportService
- ExportService
- AdminService
- S3Service

Database Layer (Purple):
- Main tables/collections:
- Users
- Bookmarks
- Tags
- Groups
- BookmarkTags
- Jobs

External Services (Red):
- S3 Storage
- OAuth Providers
- Favicon Service

##### Data Flow Indicators

- User authentication flow
- Bookmark creation/update flow
- Tag management flow
- Import/Export operations
- Admin operations

##### Additional Elements

Include:
- Version information
- Database migration flow
- Security boundaries
- API versioning (v1 endpoints)

##### Infrastructure Layer

Docker-related components:
- Nginx reverse proxy
- S6-overlay service management
- Container health checks

Remember to highlight the modular nature of the application, especially the separation between client and server components, and how the service layer abstracts database operations from the API endpoints.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        Browser["Web Browser"]
    end

    subgraph Frontend
        SvelteKit["SvelteKit Application"]
        Components["Component Library"]:::frontend
        Stores["Client Stores"]:::frontend
        Routes["Frontend Routes"]:::frontend
    end

    subgraph API
        Auth["/api/auth"]:::api
        BookmarkAPI["/api/bookmarks"]:::api
        TagAPI["/api/tags"]:::api
        GroupAPI["/api/groups"]:::api
        AdminAPI["/api/admin"]:::api
        ImportExportAPI["/api/import-export"]:::api
        FaviconAPI["/api/favicon"]:::api
    end

    subgraph Services
        BookmarkService["Bookmark Service"]:::service
        TagService["Tag Service"]:::service
        GroupService["Group Service"]:::service
        UserService["User Service"]:::service
        ImportService["Import Service"]:::service
        ExportService["Export Service"]:::service
        AdminService["Admin Service"]:::service
        S3Service["S3 Service"]:::service
    end

    subgraph Database
        DBMigrations["Migrations"]:::database
        Users[(Users)]:::database
        Bookmarks[(Bookmarks)]:::database
        Tags[(Tags)]:::database
        Groups[(Groups)]:::database
        BookmarkTags[(BookmarkTags)]:::database
        Jobs[(Jobs)]:::database
    end

    subgraph External
        S3["S3 Storage"]:::external
        OAuthProviders["OAuth Providers"]:::external
        FaviconService["Favicon Service"]:::external
    end

    %% Relationships
    Browser <--> SvelteKit
    SvelteKit --> Components
    SvelteKit --> Stores
    SvelteKit --> Routes

    Routes --> Auth
    Routes --> BookmarkAPI
    Routes --> TagAPI
    Routes --> GroupAPI
    Routes --> AdminAPI
    Routes --> ImportExportAPI
    Routes --> FaviconAPI

    Auth --> UserService
    BookmarkAPI --> BookmarkService
    TagAPI --> TagService
    GroupAPI --> GroupService
    AdminAPI --> AdminService
    ImportExportAPI --> ImportService
    ImportExportAPI --> ExportService
    FaviconAPI --> FaviconService

    BookmarkService --> Bookmarks
    TagService --> Tags
    GroupService --> Groups
    UserService --> Users
    ImportService --> Jobs
    ExportService --> Jobs
    AdminService --> Users
    S3Service --> S3

    UserService --> OAuthProviders
    FaviconAPI --> FaviconService

    %% Styles
    classDef frontend fill:#3498db,color:#fff
    classDef api fill:#2ecc71,color:#fff
    classDef service fill:#f1c40f,color:#000
    classDef database fill:#9b59b6,color:#fff
    classDef external fill:#e74c3c,color:#fff

    %% Click Events
    click Components "https://github.com/haishanh/cherry/tree/main/src/lib/components/"
    click Stores "https://github.com/haishanh/cherry/tree/main/src/lib/client/"
    click Auth "https://github.com/haishanh/cherry/tree/main/src/routes/api/auth/"
    click FaviconAPI "https://github.com/haishanh/cherry/tree/main/src/routes/api/favicon/"
    click BookmarkService "https://github.com/haishanh/cherry/blob/main/src/lib/server/services/bookmark.service.ts"
    click TagService "https://github.com/haishanh/cherry/blob/main/src/lib/server/services/tag.service.ts"
    click GroupService "https://github.com/haishanh/cherry/blob/main/src/lib/server/services/group.service.ts"
    click UserService "https://github.com/haishanh/cherry/blob/main/src/lib/server/services/user.service.ts"
    click ImportService "https://github.com/haishanh/cherry/blob/main/src/lib/server/services/import.service.ts"
    click ExportService "https://github.com/haishanh/cherry/blob/main/src/lib/server/services/export.service.ts"
    click AdminService "https://github.com/haishanh/cherry/blob/main/src/lib/server/services/admin.service.ts"
    click S3Service "https://github.com/haishanh/cherry/blob/main/src/lib/server/services/s3.service.ts"
    click DBMigrations "https://github.com/haishanh/cherry/tree/main/src/lib/server/db/migrations/"
```
