# ryukokudx/steam_tracker architecture

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

- Interactive diagram: https://gitdiagram.com/ryukokudx/steam_tracker
- Repository: https://github.com/ryukokudx/steam_tracker

## Overview

##### Project type and purpose
- Type: Full-stack automation/management system built on Google Workspace technologies.
- Purpose: Track “abandoned” items in a makerspace (“Steam Commons”), enable QR-code registration, send reminders before removal date, and allow admin actions via LINE Bot and AppSheet dashboard.

##### File structure
- Top-level:
- GAS/ (Google Apps Script source, code.gs)
- docs/ (design/operation guides, requirements, specifications)
- .claspignore, .gitignore (deployment and SCM filters)
- README.md, LICENSE
- No separate “frontend” folder—user registration UI is Google Forms (managed outside this codebase).
- Backend logic & automation lives entirely in GAS/code.gs.
- Configuration (env variables) drives external integrations (Sheets, LINE, Gmail).

##### README for additional insights
- Architecture section lists:
- Backend/Automation: GAS
- Data store: Google Sheets
- User UI: Google Forms
- Admin UI: LINE Messaging API, AppSheet
- Dev tool: clasp, GitHub, CI workflows
- Features outline how components interact (e.g., Forms → GAS → Sheets → reminder emails/LINE messages).

##### Components & interactions
a. Main components
- Users’ devices (mobile/desktop)
- Google Forms (item registration)
- Google Apps Script (code.gs)
- Google Sheets (data store)
- Gmail API (reminder emails)
- LINE Messaging API (admin notifications & controls)
- AppSheet dashboard
- CI/CD (GitHub Actions + clasp)
b. Relationships & data flow
1. User scans QR code → opens Google Form → submits item data.
2. Form submission triggers GAS function → writes row to Google Sheet.
3. Scheduled GAS trigger (time-based) queries Sheet for items nearing removal →
- Sends email via Gmail API
- Posts push notification to admin LINE group via LINE API
4. Admin clicks LINE Bot buttons → GAS callback archives item (updates Sheet).
5. AppSheet reads from same Google Sheet → shows dashboard for search/listing.
6. Developers push/pull code with clasp + GitHub Actions for CI.
c. Architectural patterns and design principles
- Event-driven automation (Form triggers & cron triggers)
- Single codebase (monolith) in GAS, external UIs for light frontend
- Declarative data storage (Sheets as “No-code DB”)
- Separation of concerns:
- Data capture (Forms)
- Business logic (GAS)
- Data storage (Sheets)
- Notifications (Gmail + LINE)
- Dashboard (AppSheet)
d. Key technologies & frameworks
- Google Apps Script (ES6-style JavaScript)
- clasp CLI for local development & deployment
- Google Sheets API
- Gmail (Apps Script MailApp or Gmail API)
- LINE Messaging API (webhook integration in GAS)
- AppSheet no-code platform
- GitHub Actions (CI for push/pull, tests, notifications)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    Users["User"]:::actor
    Admin["Admin"]:::actor

    %% User & Admin UIs
    subgraph "User & Admin Interfaces"
        Forms["Google Forms"]:::ui
        AppSheet["AppSheet Dashboard"]:::ui
        LINE_UI["LINE Bot UI"]:::ui
    end

    %% Triggers
    TimeTrigger["Time-based Trigger"]:::trigger
    Webhook["LINE Webhook"]:::trigger

    %% Core Backend
    GAS["Google Apps Script\n(code.gs)"]:::backend

    %% Data Store
    Sheets["Google Sheets"]:::data

    %% External Services
    GmailAPI["Gmail API"]:::external
    LINE_API["LINE Messaging API"]:::external

    %% Dev & CI/CD
    subgraph "Dev & CI/CD"
        CLAspire[".claspignore"]:::dev
        Workflows[".github/workflows/"]:::dev
        TeamsWF["teams-notification.yml"]:::dev
        README["README.md"]:::dev
        LICENSE["LICENSE"]:::dev
        subgraph "Documentation"
            Req["REQUIREMENTS.md"]:::dev
            Spec["SPECIFICATIONS.md"]:::dev
            CG["CLASP_GUIDE.md"]:::dev
            GG["GITHUB_GUIDE.md"]:::dev
            CMS["COMMIT_MESSAGE_SPECIFICATION.md"]:::dev
            PRC["PULLREQUESTS_COMMENT_SPECIFICATION.md"]:::dev
        end
    end

    %% Flow: User registration
    Users --> Forms
    Forms -->|"onFormSubmit trigger"| GAS
    Forms -.-> Sheets

    %% AppSheet dashboard reading data
    Admin --> AppSheet
    AppSheet -->|"read data"| Sheets

    %% LINE Bot webhook
    Admin --> LINE_UI
    LINE_UI --> Webhook
    Webhook -->|"webhook call"| GAS

    %% Scheduled trigger
    TimeTrigger -->|"time trigger"| GAS

    %% Backend to datastore
    GAS -->|"write/read rows"| Sheets

    %% Notifications
    GAS -->|"send email"| GmailAPI
    GAS -->|"post message"| LINE_API

    %% DevOps deployment flow
    CLAspire -->|"clasp filter"| GAS
    Workflows -->|"CI/CD deploy"| GAS
    TeamsWF -.-> Workflows

    %% Click events
    click GAS "https://github.com/ryukokudx/steam_tracker/blob/main/GAS/code.gs"
    click CLAspire "https://github.com/ryukokudx/steam_tracker/blob/main/.claspignore"
    click Workflows "https://github.com/ryukokudx/steam_tracker/tree/main/.github/workflows/"
    click TeamsWF "https://github.com/ryukokudx/steam_tracker/blob/main/.github/workflows/teams-notification.yml"
    click README "https://github.com/ryukokudx/steam_tracker/blob/main/README.md"
    click LICENSE "https://github.com/ryukokudx/steam_tracker/tree/main/LICENSE"
    click Req "https://github.com/ryukokudx/steam_tracker/blob/main/docs/REQUIREMENTS.md"
    click Spec "https://github.com/ryukokudx/steam_tracker/blob/main/docs/SPECIFICATIONS.md"
    click CG "https://github.com/ryukokudx/steam_tracker/blob/main/docs/CLASP_GUIDE.md"
    click GG "https://github.com/ryukokudx/steam_tracker/blob/main/docs/GITHUB_GUIDE.md"
    click CMS "https://github.com/ryukokudx/steam_tracker/blob/main/docs/COMMIT_MESSAGE_SPECIFICATION.md"
    click PRC "https://github.com/ryukokudx/steam_tracker/blob/main/docs/PULLREQUESTS_COMMENT_SPECIFICATION.md"

    %% Styles
    classDef actor fill:#FFFFFF,stroke:#333,stroke-width:1px,shape:diamond
    classDef ui fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef backend fill:#98FB98,stroke:#333,stroke-width:1px
    classDef data fill:#E0FFE0,stroke:#333,stroke-width:1px,shape:cylinder
    classDef external fill:#FFD580,stroke:#333,stroke-width:1px
    classDef dev fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef trigger fill:#FFFFFF,stroke:#333,stroke-width:1px,stroke-dasharray:5 5
```
