# masnormen/ziyo architecture

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

- Interactive diagram: https://gitdiagram.com/masnormen/ziyo
- Repository: https://github.com/masnormen/ziyo

## Overview

##### High-Level Architecture Overview

a) Frontend Application (ziyo-fe)
- Next.js-based web application
- Client-side search interface
- Kanji detail pages
- SEO and OpenGraph optimization

b) Backend Service (ziyo-be)
- Hono.js-based API server
- OpenGraph image generation
- SQLite database integration
- Typesense integration

c) Search Engine
- Typesense instance
- Kanji index and search functionality

##### Component Relationships

a) Client Layer:
- Sub-components:
- Search UI
- Kanji detail views
- Settings management
- Query hooks layer

b) API Layer:
- Connections to:
- OpenGraph image generator
- SQLite database
- Typesense search engine

c) Data Layer:
- SQLite database (kanji.sqlite)
- Typesense search engine
- Static assets

##### Specific Implementation Details

- Blue rectangles for frontend components
- Green rectangles for backend services
- Purple hexagons for external services
- Red diamonds for critical infrastructure components

Following interactions:

- User → Frontend: Search requests and navigation
- Frontend → Backend: API calls
- Backend → Typesense: Search queries
- Backend → SQLite: Kanji data retrieval
- Backend → OpenGraph: Image generation

**[Client Layer (Next.js)]**
- ↓
**[API Layer (Hono.js)]**
- ↓
**[Data Layer (Typesense + SQLite)]**

##### Search functionality as it's the core feature
- Typesense integration
- Multiple search methods (readings, meanings)
- Real-time search results

##### Development tooling
- Docker containers
- GitHub Actions workflows
- Type generation scripts

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        FE[Next.js Frontend]:::frontend
        Search["Search Interface"]:::frontend
        KanjiDetail["Kanji Detail Pages"]:::frontend
        Settings["Settings Management"]:::frontend
        QueryHooks["Query Hooks Layer"]:::frontend
        SEO["SEO Configuration"]:::frontend
        APIClient["API Client"]:::frontend
        
        FE --> Search
        FE --> KanjiDetail
        FE --> Settings
        FE --> QueryHooks
        FE --> SEO
        FE --> APIClient
    end

    subgraph API
        BE[Hono.js Backend]:::backend
        OG["OpenGraph Generator"]:::backend
        TypesenseInt["Typesense Integration"]:::backend
        
        BE --> OG
        BE --> TypesenseInt
    end

    subgraph Data
        DB[(SQLite Database)]:::database
        TS[("Typesense Search")]:::search
        Assets[("Static Assets")]:::storage
    end

    subgraph Infrastructure
        Docker[("Docker Containers")]:::infra
        GH["GitHub Actions"]:::infra
        TypeGen["API Type Generation"]:::infra
    end

    subgraph Shared
        UI["UI Components"]:::shared
        Types["Shared Types"]:::shared
    end

    %% Connections
    Search --> APIClient
    KanjiDetail --> APIClient
    Settings --> APIClient
    APIClient --> BE
    BE --> DB
    BE --> TS
    QueryHooks --> APIClient
    UI --> FE
    Types --> FE
    Types --> BE

    %% Click Events
    click Search "https://github.com/masnormen/ziyo/blob/main/apps/ziyo-fe/src/components/Search.tsx"
    click KanjiDetail "https://github.com/masnormen/ziyo/blob/main/apps/ziyo-fe/src/pages/kanji/[character]/index.tsx"
    click Settings "https://github.com/masnormen/ziyo/blob/main/apps/ziyo-fe/src/components/Settings.tsx"
    click QueryHooks "https://github.com/masnormen/ziyo/tree/main/apps/ziyo-fe/src/hooks/query/"
    click SEO "https://github.com/masnormen/ziyo/blob/main/apps/ziyo-fe/src/configs/next-seo.ts"
    click APIClient "https://github.com/masnormen/ziyo/blob/main/apps/ziyo-fe/src/lib/api.ts"
    click BE "https://github.com/masnormen/ziyo/blob/main/apps/ziyo-be/src/index.ts"
    click OG "https://github.com/masnormen/ziyo/blob/main/apps/ziyo-be/src/og-images.tsx"
    click DB "https://github.com/masnormen/ziyo/blob/main/apps/ziyo-be/src/assets/kanji.sqlite"
    click TypesenseInt "https://github.com/masnormen/ziyo/blob/main/apps/ziyo-be/src/lib/typesense.ts"
    click TS "https://github.com/masnormen/ziyo/blob/main/scripts/typesense/setup.ts"
    click UI "https://github.com/masnormen/ziyo/tree/main/libs/ui/src/components/ui/"
    click Types "https://github.com/masnormen/ziyo/blob/main/libs/types/src/index.ts"
    click Docker "https://github.com/masnormen/ziyo/tree/main/apps/ziyo-be/Dockerfile"
    click GH "https://github.com/masnormen/ziyo/tree/main/.github/workflows/"
    click TypeGen "https://github.com/masnormen/ziyo/blob/main/apps/ziyo-fe/scripts/gen-api-types.sh"

    %% Styles
    classDef frontend fill:#3b82f6,color:white
    classDef backend fill:#22c55e,color:white
    classDef database fill:#eab308,color:black
    classDef search fill:#a855f7,color:white
    classDef storage fill:#f97316,color:white
    classDef infra fill:#ef4444,color:white
    classDef shared fill:#06b6d4,color:white

    %% Legend
    subgraph Legend
        F[Frontend]:::frontend
        B[Backend]:::backend
        D[(Database)]:::database
        S[Search]:::search
        ST[(Storage)]:::storage
        I[Infrastructure]:::infra
        SH[Shared]:::shared
    end
```
