# unagi22/rcat architecture

> Architecture diagram of the GitHub repository unagi22/rcat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/unagi22/rcat
- Repository: https://github.com/unagi22/rcat

## Overview

##### What this project is (type + purpose)
From the file tree + README, this is a **single-page frontend web app** built with **React + TypeScript + Vite**. It has **no separate backend service** in the repository. Instead, it calls the **Google Gemini API** directly from the client using an API key provided via `.env.local`.

The app has two primary UI modes/roles indicated by components:
- `components/AdminView.tsx`
- `components/CustomerView.tsx`

It also has two “service” modules:
- `services/gemini.ts` → external AI API integration
- `services/storage.ts` → client-side persistence (likely localStorage / indexedDB / in-memory abstraction)

So the architecture is essentially: **Browser UI → App logic → (Gemini API + local persistence)**.

##### App entry + composition
- `index.html` → Vite HTML entry template
- `index.tsx` → React root render (mounts `<App />`)
- `App.tsx` → top-level orchestrator: routing/conditional rendering between Admin vs Customer, shared state, and service usage

##### UI “feature slices”
- `components/AdminView.tsx` → Admin-facing flows and UI
- `components/CustomerView.tsx` → Customer-facing flows and UI

##### Domain/config/types
- `constants.ts` → app-level configuration/flags/prompts/defaults

##### Integration layer (“services”)
- `services/gemini.ts` → the “AI Client” adapter wrapping Gemini SDK/HTTP calls
- `services/storage.ts` → persistence adapter (client storage abstraction)

##### Tooling/build (usually a separate “build pipeline” lane
- `vite.config.ts`, `tsconfig.json`, `package.json` → build/test/dev tooling and dependency graph

##### User (Actor)
- Optionally split into **Admin User** and **Customer User** since there are distinct views.
##### Browser (Execution Environment)
- Contains the React SPA.
##### React SPA (Container)
- Sub-components inside it:
- `App.tsx` (composition + state)
- `AdminView` (UI feature)
- `CustomerView` (UI feature)
- `Gemini Service Adapter` (`services/gemini.ts`)
- `Storage Service Adapter` (`services/storage.ts`)
- `Constants/Types` (`constants.ts`, `types.ts`)
##### External Service: Google Gemini API
- Called over HTTPS.
##### Client Storage
- LocalStorage/IndexedDB (whatever `storage.ts` uses). Even if it’s “not a server,” it’s a distinct runtime dependency.

- Admin User → Browser → React SPA
- Customer User → Browser → React SPA
- Views/App → `services/gemini.ts` → **Gemini API**
- Views/App → `services/storage.ts` → **Browser Storage**
- `.env.local (GEMINI_API_KEY)` → `services/gemini.ts` (show as configuration injection at build/runtime)

**Important note to capture explicitly:**

This explains how code becomes a deployed artifact.

- Developer workstation
- Node.js + npm
- Vite dev server (`npm run dev`)
- Vite build output (static assets: HTML/CSS/JS bundle)
- Hosting/CDN (where the static site is deployed; if unknown, label generically: “Static hosting (e.g., Cloudflare Pages / Vercel / Netlify)”)

- Developer → `npm install` (package.json dependencies)
- Developer → `npm run dev` → Vite dev server → Browser
- CI/CD (optional generic) → `vite build` → static hosting → end users

##### Architectural patterns/design principles to highlight
Based on file layout:
- **Separation of concerns**:
- UI components in `components/`
- External integrations behind `services/`
- Shared constants/types centralized
- **Adapter pattern** for integrations:
- `services/gemini.ts` abstracts Gemini calls
- `services/storage.ts` abstracts persistence
- **Role-based UI slices**:
- Admin vs Customer flows split into separate components

Of these explicitly:

##### Clear labels
Use filenames in parentheses to keep it grounded:
- “Gemini Client Adapter (`services/gemini.ts`)"
- “Admin View (`components/AdminView.tsx`)”
- “App Shell (`App.tsx`)”

- “Prompt / context → Generate content”
- “AI response → Render UI”
- “Save/Load session state / settings”

##### Left: Actors
- Admin
- Customer

##### Middle: Browser boundary
- React SPA
- App.tsx
- AdminView
- CustomerView
- services/gemini.ts
- services/storage.ts

##### Bottom (inside browser): Browser Storage
- Local storage / IndexedDB

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Runtime Architecture
  %% =========================
  subgraph RUNTIME["Runtime Architecture (Production)"]
    direction TB

    subgraph ACTORS["Actors"]
      direction TB
      AdminUser(["Admin User"]):::actor
      CustomerUser(["Customer User"]):::actor
    end

    subgraph BROWSER["Browser Runtime Boundary (SPA executes here)"]
      direction TB

      Browser(["Web Browser"]):::browser

      subgraph SPA["React + TypeScript SPA (Vite)"]
        direction TB

        IndexHtml["HTML Entry Template (index.html)"]:::config
        ReactRoot["React Root Mount (index.tsx)"]:::ui
        AppShell["App Shell / Orchestrator (App.tsx)"]:::ui

        subgraph UI["UI Feature Slices (components/)"]
          direction TB
          AdminView["Admin View (components/AdminView.tsx)"]:::ui
          CustomerView["Customer View (components/CustomerView.tsx)"]:::ui
        end

        subgraph INTEGRATIONS["Integration Layer (services/)"]
          direction TB
          GeminiAdapter["Gemini Client Adapter (services/gemini.ts)"]:::svc
          StorageAdapter["Storage Adapter (services/storage.ts)"]:::svc
        end

        subgraph DOMAIN["Domain / Shared Definitions"]
          direction TB
          Constants["Constants / Defaults (constants.ts)"]:::config
          Types["TypeScript Types (types.ts)"]:::config
          Metadata["App Metadata (metadata.json)"]:::config
        end

        EnvKey["Config: GEMINI_API_KEY (.env.local via Vite env injection)"]:::secret
      end

      ClientStorage[("Client Storage (LocalStorage/IndexedDB)")]:::db
    end

    subgraph EXTERNAL["External Services (Untrusted Network Boundary)"]
      direction TB
      GeminiAPI["Google Gemini API"]:::external
    end

    SecurityNote["NOTE: No backend in repo.\nAPI key is configured client-side; exposure risk unless proxied via a backend."]:::note
  end

  %% Runtime flows (vertical, labeled)
  AdminUser -->|"uses"| Browser
  CustomerUser -->|"uses"| Browser

  Browser -->|"loads SPA"| IndexHtml
  IndexHtml -->|"bootstraps"| ReactRoot
  ReactRoot -->|"mounts <App />"| AppShell

  AppShell -->|"composes"| AdminView
  AppShell -->|"composes"| CustomerView

  AdminView -->|"prompt/context"| GeminiAdapter
  CustomerView -->|"prompt/context"| GeminiAdapter
  GeminiAdapter -->|"HTTPS generateContent()"| GeminiAPI
  GeminiAPI -->|"AI response"| GeminiAdapter
  GeminiAdapter -->|"content/results"| AdminView
  GeminiAdapter -->|"content/results"| CustomerView

  AdminView -->|"save/load state"| StorageAdapter
  CustomerView -->|"save/load state"| StorageAdapter
  StorageAdapter -->|"read/write"| ClientStorage

  Constants -->|"defaults/prompts"| AppShell
  Types -->|"models/shapes"| AppShell
  Metadata -->|"build/runtime descriptor"| AppShell

  EnvKey -->|"injects key"| GeminiAdapter
  EnvKey -.->|"risk callout"| SecurityNote
  GeminiAdapter -.->|"direct client call (no backend)"| SecurityNote

  %% =========================
  %% Build / Dev / Deploy
  %% =========================
  subgraph PIPELINE["Build / Dev / Deploy (Pipeline View)"]
    direction TB

    Dev(["Developer Workstation"]):::actor
    NodeNpm["Node.js + npm"]:::tool
    Pkg["Dependencies & Scripts (package.json)"]:::tool
    ViteCfg["Vite Config (vite.config.ts)"]:::tool
    TsCfg["TypeScript Config (tsconfig.json)"]:::tool
    Readme["Project Documentation (README.md)"]:::doc

    DevServer["Vite Dev Server (npm run dev)"]:::tool
    BuildStep["Vite Build (npm run build)"]:::tool
    StaticAssets[("Build Output: Static Assets (HTML/CSS/JS bundle)")]:::artifact
    Hosting["Static Hosting / CDN (e.g., Vercel/Netlify/Cloudflare Pages)"]:::external

    EndUsers(["End Users (Admin + Customer)"]):::actor
  end

  %% Pipeline flows (vertical)
  Dev -->|"npm install"| NodeNpm
  NodeNpm -->|"reads"| Pkg
  NodeNpm -->|"uses"| ViteCfg
  NodeNpm -->|"uses"| TsCfg
  Dev -->|"refer"| Readme

  Dev -->|"npm run dev"| DevServer
  DevServer -->|"serves SPA"| Browser

  Dev -->|"npm run build"| BuildStep
  BuildStep -->|"emits"| StaticAssets
  StaticAssets -->|"deploy"| Hosting
  Hosting -->|"serves over HTTPS"| EndUsers
  EndUsers -->|"open site"| Browser

  %% =========================
  %% Click events (from component mapping)
  %% =========================
  click IndexHtml "https://github.com/unagi22/rcat/blob/main/index.html"
  click ReactRoot "https://github.com/unagi22/rcat/blob/main/index.tsx"
  click AppShell "https://github.com/unagi22/rcat/blob/main/App.tsx"
  click AdminView "https://github.com/unagi22/rcat/blob/main/components/AdminView.tsx"
  click CustomerView "https://github.com/unagi22/rcat/blob/main/components/CustomerView.tsx"
  click UI "https://github.com/unagi22/rcat/tree/main/components/"
  click GeminiAdapter "https://github.com/unagi22/rcat/blob/main/services/gemini.ts"
  click StorageAdapter "https://github.com/unagi22/rcat/blob/main/services/storage.ts"
  click INTEGRATIONS "https://github.com/unagi22/rcat/tree/main/services/"
  click Constants "https://github.com/unagi22/rcat/blob/main/constants.ts"
  click Types "https://github.com/unagi22/rcat/blob/main/types.ts"
  click Metadata "https://github.com/unagi22/rcat/blob/main/metadata.json"
  click ViteCfg "https://github.com/unagi22/rcat/blob/main/vite.config.ts"
  click TsCfg "https://github.com/unagi22/rcat/blob/main/tsconfig.json"
  click Pkg "https://github.com/unagi22/rcat/blob/main/package.json"
  click Readme "https://github.com/unagi22/rcat/blob/main/README.md"

  %% =========================
  %% Styles (color critical)
  %% =========================
  classDef actor fill:#ECEFF4,stroke:#4C566A,stroke-width:1px,color:#2E3440
  classDef browser fill:#E5E9F0,stroke:#5E81AC,stroke-width:1px,color:#2E3440
  classDef ui fill:#D7EBFF,stroke:#1F6FEB,stroke-width:1px,color:#0B1F3A
  classDef svc fill:#E9D5FF,stroke:#7C3AED,stroke-width:1px,color:#2B1645
  classDef db fill:#D1FAE5,stroke:#059669,stroke-width:1px,color:#063B2C
  classDef external fill:#FFE4D6,stroke:#F97316,stroke-width:1px,color:#4A1B00
  classDef config fill:#FFF7CC,stroke:#B58900,stroke-width:1px,color:#3B2F00
  classDef tool fill:#E0F2FE,stroke:#0284C7,stroke-width:1px,color:#062B3D
  classDef artifact fill:#E2E8F0,stroke:#64748B,stroke-width:1px,color:#0F172A
  classDef doc fill:#FCE7F3,stroke:#DB2777,stroke-width:1px,color:#3B0A20
  classDef note fill:#FFF1F2,stroke:#E11D48,stroke-width:1px,color:#450A0A,stroke-dasharray: 4 3
  classDef secret fill:#FFE4E6,stroke:#BE123C,stroke-width:1px,color:#4C0519
```
