# jonrgull/convertium architecture

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

- Interactive diagram: https://gitdiagram.com/jonrgull/convertium
- Repository: https://github.com/jonrgull/convertium

## Overview

##### Project type and purpose
- This is a full-stack, single-page Next.js application (“Convertium”) for converting foreign names or Japanese text between Hiragana, full-width Katakana, half-width Katakana, and English via Google Cloud Translate.
- The README confirms: it’s built in Next.js + TypeScript with Chakra UI, uses two conversion libraries on the client, and calls Google Cloud Translate via a Next.js API route.

##### File structure
- Top-level:
- components/         ← React UI components (Footer, Nav, plus jpn-specific converters)
- pages/              ← Next.js pages & API routes
– index.tsx        ← main UI page
– api/translate.ts ← server-side function calling Google Translate
- public/             ← static assets (images, gifs)
- styles/             ← global CSS
- package.json, tsconfig.json, pnpm-lock.yaml, etc.
- The presence of pages/api identifies an internal backend (Node) layer.
- UI logic (romaji-conv, encoding-japanese) lives in components/jpn; external API calls live in pages/api.

##### README for additional insights
- No database is in use.
- Key tech: Next.js (SSR/CSR hybrid), TypeScript, Chakra UI, Google Cloud Translate API, romaji-conv, encoding-japanese.

a. Main components:
1. Client Browser (React/Chakra UI)
2. Next.js Frontend (pages, components)
3. Next.js API Layer (pages/api/translate.ts)
4. External Service – Google Cloud Translate API
5. Conversion Libraries (romaji-conv, encoding-japanese)
6. Static Assets Server (public folder)
b. Relationships & data flows:
- User inputs text in the Client Browser.
- For simple conversions (Hiragana↔Katakana/half-width), client calls romaji-conv & encoding-japanese directly in the browser.
- For English→Japanese translation or other translations, browser issues HTTP POST to Next.js API (/api/translate).
- API route invokes Google Cloud Translate, processes the result server-side, returns JSON.
- Client receives JSON, updates UI.
- Static assets (Sample.gif) served from the public folder via Next.js.

c. Architectural patterns / design principles:
- Monorepo full-stack: UI and API in same codebase.
- API Routing: Next.js “pages/api” directory pattern.
- Component-based UI (React + Chakra UI).
- Separation of concerns: conversion logic split between client libraries and server API calls.
- No persistent storage; stateless conversion.

d. Relevant technologies:
- Next.js (React server/client rendering)
- TypeScript
- Chakra UI (design system)
- romaji-conv, encoding-japanese (client conversion)
- Google Cloud Translate API (third-party translation)

##### Final guidance
- Timing (e.g., SSR vs. CSR) if relevant.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser)"
        UIWrapper["Global App Wrapper"]:::frontend
        Nav["Navigation Component"]:::frontend
        Footer["Footer Component"]:::frontend
        MainUI["Main UI Page"]:::frontend
        subgraph "Conversion Libraries"
            ConvFull["Full-width Katakana Converter"]:::conversion
            ConvHalf["Half-width Katakana Converter"]:::conversion
            ConvHira["Hiragana Converter"]:::conversion
            EngBtn["English Translate Button"]:::conversion
        end
    end

    %% Server Layer
    subgraph "Server (Next.js)"
        API["Google Cloud Translate API Route"]:::api
        Static["Static Assets Server"]:::static
        GlobalStyles["Global Styles"]:::static
    end

    %% External Service
    External["Google Cloud Translate Service"]:::external

    %% Data Flows
    UIWrapper --> MainUI
    MainUI --> ConvFull
    MainUI --> ConvHalf
    MainUI --> ConvHira
    MainUI --> EngBtn
    EngBtn -->|"POST { text }"| API
    API -->|"HTTPS"| External
    External -->|"JSON { translatedText }"| API
    API -->|"JSON response"| MainUI
    MainUI -->|"loads assets"| Static
    UIWrapper --> GlobalStyles

    %% Click Events
    click UIWrapper "https://github.com/jonrgull/convertium/blob/main/pages/_app.tsx"
    click MainUI "https://github.com/jonrgull/convertium/blob/main/pages/index.tsx"
    click Nav "https://github.com/jonrgull/convertium/blob/main/components/Nav.tsx"
    click Footer "https://github.com/jonrgull/convertium/blob/main/components/Footer.tsx"
    click ConvFull "https://github.com/jonrgull/convertium/blob/main/components/jpn/ConvertFull.tsx"
    click ConvHalf "https://github.com/jonrgull/convertium/blob/main/components/jpn/ConvertHalf.tsx"
    click ConvHira "https://github.com/jonrgull/convertium/blob/main/components/jpn/ConvertHira.tsx"
    click EngBtn "https://github.com/jonrgull/convertium/blob/main/components/jpn/EngTranslateBtn.tsx"
    click API "https://github.com/jonrgull/convertium/blob/main/pages/api/translate.ts"
    click Static "https://github.com/jonrgull/convertium/tree/main/public/"
    click GlobalStyles "https://github.com/jonrgull/convertium/blob/main/styles/globals.css"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef conversion fill:#E6F4EA,stroke:#28a745,color:#28a745
    classDef api fill:#E3F2FD,stroke:#2196F3,color:#0D47A1
    classDef external fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef static fill:#F5F5F5,stroke:#9E9E9E,color:#424242
```
