# bfiliks/comment-rule-labeling architecture

> Architecture diagram of the GitHub repository bfiliks/comment-rule-labeling, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bfiliks/comment-rule-labeling
- Repository: https://github.com/bfiliks/comment-rule-labeling

## Overview

##### Project Type and Purpose
- This is a full‐stack, single‐page annotation tool built with Streamlit (Python) that lets multiple annotators label YouTube comments against community rules.
- The “frontend” and “backend” live in the same codebase (app.py) and run on Streamlit Cloud, while Google Sheets serves as the shared, collaborative data store.

##### File Structure Analysis
- Top level:
- app.py – the monolithic Streamlit application (UI + business logic)
- requirements.txt – Python dependencies (streamlit, gspread, pandas, etc.)
- example_data.csv – sample input data
- .streamlit/config.toml – theming, favicon, and Streamlit settings
- assets/ – static banner image
- No separate “frontend” or “backend” directories; the pattern is a server‐driven UI (Streamlit) with external data integration.
- Configuration & deployment: devcontainer for local dev, GitHub templates, Streamlit secrets for gspread credentials.

##### Key Architecture Insights from README
- Annotator authentication is name‐based (no heavy IAM).
- Data flow: CSV upload → in‐memory DataFrame → write/read to Google Sheets via gspread API → display/progress tracking.
- Real‐time multi‐annotator sync: uses Google Sheets locking or row‐status checks to avoid duplication.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Presentation Tier
  subgraph "Presentation Tier" 
    direction TB
    Browser["Annotator Browser"]:::ui
  end

  %% Application Tier
  subgraph "Application Tier (Streamlit App Server)" 
    direction TB
    UIlayer["UI Layer\n(Streamlit widgets & pages)"]:::app
    BizLogic["Business Logic Layer\n(label assignment, flagging, progress computation)"]:::app
    DataAccess["Data Access Layer\n(gspread client & pandas integration)"]:::app
  end

  %% Data Tier
  subgraph "Data Tier"
    direction TB
    GoogleSheets[(Google Sheets)]:::external
  end

  %% Infrastructure & Config
  subgraph "Infrastructure & Config"
    direction TB
    SecretsVault["Streamlit Secrets Management"]:::external
    StaticAssets["Static Assets\n(banner image)"]:::config
    LocalCSV["Sample Input Data\n(example_data.csv)"]:::config
    StreamlitConfig["Streamlit Configuration\n(.streamlit/config.toml)"]:::config
    Requirements["Python Dependencies\n(requirements.txt)"]:::config
    DevContainer["DevContainer Config\n(.devcontainer/devcontainer.json)"]:::config
    IssueTemplates["GitHub Issue Templates\n(.github/ISSUE_TEMPLATE)"]:::config
    Docs["Project Docs & Guidelines\n(README.md, CONTRIBUTING.md)"]:::config
    License["License File\n(LICENSE)"]:::config
  end

  %% Platform
  StreamlitCloud["Streamlit Cloud"]:::platform

  %% Connections
  Browser -->|"Interact via Streamlit UI"| UIlayer
  Browser -->|"Upload CSV"| UIlayer
  UIlayer -->|"Invoke business logic"| BizLogic
  UIlayer -->|"Load example_data.csv"| DataAccess
  BizLogic -->|"Fetch/Save annotations"| DataAccess
  DataAccess -->|"Read/Write rows via gspread\nLock row/check status"| GoogleSheets
  SecretsVault -->|"Provide gspread_credentials.json"| DataAccess
  StaticAssets -->|"Serve banner image"| UIlayer
  BizLogic -->|"Export consolidated labels"| Browser
  StreamlitCloud -->|"Hosts app.py"| UIlayer

  %% Click Events
  click UIlayer "https://github.com/bfiliks/comment-rule-labeling/blob/main/app.py"
  click BizLogic "https://github.com/bfiliks/comment-rule-labeling/blob/main/app.py"
  click DataAccess "https://github.com/bfiliks/comment-rule-labeling/blob/main/app.py"
  click StaticAssets "https://github.com/bfiliks/comment-rule-labeling/blob/main/assets/streamlit_banner.png"
  click LocalCSV "https://github.com/bfiliks/comment-rule-labeling/blob/main/example_data.csv"
  click StreamlitConfig "https://github.com/bfiliks/comment-rule-labeling/blob/main/.streamlit/config.toml"
  click Requirements "https://github.com/bfiliks/comment-rule-labeling/blob/main/requirements.txt"
  click DevContainer "https://github.com/bfiliks/comment-rule-labeling/blob/main/.devcontainer/devcontainer.json"
  click IssueTemplates "https://github.com/bfiliks/comment-rule-labeling/tree/main/.github/ISSUE_TEMPLATE"
  click Docs "https://github.com/bfiliks/comment-rule-labeling/blob/main/README.md"
  click Docs "https://github.com/bfiliks/comment-rule-labeling/blob/main/CONTRIBUTING.md"
  click License "https://github.com/bfiliks/comment-rule-labeling/tree/main/LICENSE"

  %% Styles
  classDef ui fill:#cce5ff,stroke:#004085,color:#004085
  classDef app fill:#d4edda,stroke:#155724,color:#155724
  classDef external fill:#fff3cd,stroke:#856404,color:#856404
  classDef config fill:#e2e3e5,stroke:#6c757d,color:#6c757d
  classDef platform fill:#d1ecf1,stroke:#0c5460,color:#0c5460
```
