# eateamagon/kcinventory architecture

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

- Interactive diagram: https://gitdiagram.com/eateamagon/kcinventory
- Repository: https://github.com/eateamagon/kcinventory

## Overview

##### Project type + purpose (from file tree + README)
This is a **Google Apps Script (GAS)** project for an **inventory tracker** (“Kate Collins Middle School Inventory Tracker”). The structure is the classic GAS web app pattern:

- **`Code.gs`**: server-side Apps Script (runs on Google’s servers)
- **`Index.html`**: client-side UI (HTML/JS served by Apps Script’s HTML service)
- No separate backend framework/server, no package manager—deployment is typically **“Deploy as Web App”** inside Apps Script.
- Since GAS apps commonly store data in **Google Sheets**, treat Sheets/Drive as the likely “database layer” even if the README doesn’t explicitly say so.

##### Client/UI layer
- **Browser**
- **`Index.html` (UI)**
- HTML/CSS layout
- Client-side JavaScript
- Calls into server via `google.script.run` (typical GAS pattern) or via web endpoints (`doGet`, `doPost`) depending on implementation.

##### Server/runtime layer (Google-managed)
- **Google Apps Script runtime**
- **`Code.gs` (Server logic)**
- Web entrypoints: `doGet(e)` / `doPost(e)` (common)
- Business operations: “add item”, “check out”, “return”, “search”, “list inventory”, etc. (infer from inventory tracker purpose)
- Data access functions: reads/writes to Sheets, possibly Drive, maybe PropertiesService.

##### Data layer (Google services)
- **Google Sheets** (most likely persistent store)
- Inventory table(s)
- Transaction history (check-out / return logs)
- Optionally also show:
- **Google Drive** (hosting/permissions for the spreadsheet)
- **Apps Script PropertiesService** (config, spreadsheet IDs, etc.)
- **Google Authentication / Authorization** (who can access, “execute as”, domain restrictions)

##### Deployment / hosting boundary
- **Apps Script Web App deployment** (the hosted URL, versioning, access settings)

##### User → Browser → Index.html
- User loads the web app URL
- Apps Script serves `Index.html` (via HTML Service)

##### Index.html → Code.gs
- Client triggers actions (buttons/forms)
- Calls server functions:
- `google.script.run.<functionName>(...)` (RPC-style)
- or HTTP calls to `doPost`/`doGet` if implemented that way

##### Code.gs → Google Sheets (and/or Drive)
- Server reads/writes inventory data
- Updates rows, appends logs, queries items

##### Code.gs → Index.html
- Returns data (lists, item details, success/error states)
- UI rerenders

##### (If applicable) AuthN/AuthZ boundary
- Web app access rules (only domain users, only specific accounts, etc.)
- “Execute as” setting impacts spreadsheet permissions and auditing

##### Architectural patterns to highlight (specific to GAS inventory apps)

- **Serverless backend**: no custom server; Apps Script is the backend.
- **Thin client / RPC**: UI is mostly a view/controller calling server functions.
- **Spreadsheet-as-database**: persistence and “queries” are implemented via Sheets operations.
- **Permission-driven design**: spreadsheet access depends on deployment settings + the executing identity.
- **Single-repo, two-tier**: “frontend file” + “backend file” but both deployed as one web app.

##### Don’t overthink it: “separate into as many components as possible” (but still accurate)
- **UI rendering**
- **UI event handling**
- **Server endpoints**
- **Business logic**
- **Data access**
- **Persistence store**
- **Identity/permission model**
- **Deployment boundary**

To make it “best and most accurate,” open `Code.gs` and confirm:
- Does it use `doGet` / `doPost`?
- Does it call `SpreadsheetApp.openById(...)` or `openByUrl(...)` (confirms Sheets as DB)?
- Any use of `DriveApp`, `PropertiesService`, `Session`, `OAuth` scopes?
- Any roles (admin vs staff), or domain restriction assumptions?

##### Google Sheets (Inventory Spreadsheet)

- Staff → Browser (use)
- Browser → Apps Script (load UI)
- Browser ⇄ Apps Script (actions / responses)
- Apps Script ⇄ Sheets (CRUD)

That’s the cleanest representation of this specific repo’s architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Level 1: System Context
  %% =========================
  subgraph "System Context (Level 1)"
    direction TB
    Staff["Staff / Inventory Manager"]:::actor

    KCInv["KCInventory Web App (Google Apps Script)"]:::system

    Auth["Google Workspace Authentication<br/>(AuthN/AuthZ + domain policy)"]:::external
    Sheets["Google Sheets<br/>(Inventory + Transactions)"]:::datastore

    Staff -->|"uses"| KCInv
    KCInv -->|"relies_on"| Auth
    KCInv -->|"read_write"| Sheets
  end

  %% =========================
  %% Level 2: Container Diagram
  %% =========================
  subgraph "Container Diagram (Level 2)"
    direction TB

    subgraph "Public Internet / Client Device"
      direction TB
      Browser["Browser"]:::container
      UI["Index.html<br/>(UI: HTML/CSS/JS)"]:::frontend
    end

    subgraph "Google Workspace / Google Cloud Boundary"
      direction TB
      Deploy["Apps Script Web App Deployment<br/>(Hosted URL + access settings)"]:::platform
      GAS["Google Apps Script Runtime"]:::platform
      Server["Code.gs<br/>(Server Logic)"]:::backend

      GAuth["Google Account / Domain Access Rules<br/>(Execute as + sharing)"]:::external
      GSheets["Google Sheets<br/>(Spreadsheet-as-Database)"]:::datastore
      Drive["Google Drive<br/>(Spreadsheet file + permissions)"]:::external
      Props["PropertiesService<br/>(Config: Spreadsheet IDs, etc.)"]:::external
    end

    Browser -->|"navigates_to_web_app_URL"| Deploy
    Deploy -->|"serves_HTML_(HTML_Service)"| UI
    UI -->|"renders_in"| Browser

    UI -->|"RPC_google.script.run"| Server
    Server -->|"returns_JSON/HTML_fragments"| UI

    Server -->|"SpreadsheetApp_CRUD"| GSheets
    Server -->|"DriveApp_permissions/locate_file"| Drive
    Server -->|"get_set_config"| Props
    Deploy -->|"AuthN/AuthZ_enforced_by"| GAuth

    Drive -->|"hosts_spreadsheet"| GSheets
  end

  %% =========================
  %% Level 3: Component Diagram
  %% =========================
  subgraph "Component Diagram (Level 3)"
    direction TB

    subgraph "Client Components (Index.html)"
      direction TB
      View["View Layer<br/>(Forms, Tables, Layout)"]:::frontend
      UIController["UI Event Handlers<br/>(Buttons, Submit, Search)"]:::frontend
      ClientAdapter["Client Data Adapter<br/>(google.script.run calls)"]:::frontend

      View -->|"user_events"| UIController
      UIController -->|"invoke"| ClientAdapter
    end

    subgraph "Server Components (Code.gs)"
      direction TB
      WebHandlers["Web Handlers<br/>(doGet/doPost, HTML templating)"]:::backend
      Validation["Validation + Error Handling"]:::backend
      InventorySvc["Inventory Service<br/>(add/check-out/return/search/list)"]:::backend
      SheetRepo["Sheet Repository / DAO<br/>(tab reads/writes, queries)"]:::backend
      RoleChecks["Auth / Role Checks<br/>(domain/users permissions)"]:::backend

      WebHandlers -->|"calls"| Validation
      WebHandlers -->|"calls"| InventorySvc
      InventorySvc -->|"uses"| RoleChecks
      InventorySvc -->|"uses"| SheetRepo
      Validation -->|"guards"| InventorySvc
    end

    ClientAdapter -->|"RPC_calls"| WebHandlers
    SheetRepo -->|"CRUD_rows"| GSheets
  end

  %% =========================
  %% Click Events (from component mapping)
  %% =========================
  click UI "https://github.com/eateamagon/kcinventory/blob/main/Index.html"
  click Server "https://github.com/eateamagon/kcinventory/blob/main/Code.gs"
  click KCInv "https://github.com/eateamagon/kcinventory/blob/main/README.md"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#ffffff,stroke:#111827,stroke-width:2px,color:#111827;
  classDef system fill:#e0f2fe,stroke:#0369a1,stroke-width:2px,color:#0c4a6e;
  classDef container fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px,color:#1e3a8a;
  classDef frontend fill:#bfdbfe,stroke:#1d4ed8,stroke-width:2px,color:#1e3a8a;
  classDef backend fill:#c7d2fe,stroke:#4338ca,stroke-width:2px,color:#312e81;
  classDef platform fill:#e5e7eb,stroke:#374151,stroke-width:2px,color:#111827;
  classDef datastore fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d;
  classDef external fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#111827;
```
