# lkduy2602/svibox architecture

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

- Interactive diagram: https://gitdiagram.com/lkduy2602/svibox
- Repository: https://github.com/lkduy2602/svibox

## Overview

##### Project Type & Purpose
- This is a backend-only microservice built on Google Apps Script.
- It exposes POST endpoints (via `doPost`) to handle authentication, user management, and media metadata operations.
- Data persistence lives in Google Sheets. Error notifications are sent via Gmail.

##### File Structure (Layered MVC-Style)
- appsscript.json / .clasp.json – project config for Google Apps Script & clasp.
- src/main.js – entrypoint, routes incoming POST requests to controllers.
- src/controller – HTTP handler layer (auth.controller, user.controller, media.controller).
- src/service – business logic (auth.service, user.service, media.service).
- src/repository – data access (factory.repository routes calls to sheet-based repositories).
- src/entity – data models (auth.entity, user.entity, media.entity).
- src/validator – input validation before business logic.
- src/_utils – helpers (auth tokens, email, environment config, response wrappers, validation).

##### Readme Insights
- Google Sheets as primary datastore.
- Uses clasp for deployment & development.
- Requires POST calls against a deployed Apps Script URL.
- Initial setup: run `setUp()` in main.gs to provision sheets.

##### Main Components & Interactions
A. External Clients (e.g. Frontend, Postman, Other Services)
→ send HTTP POST with JSON payload.
B. Google Apps Script Execution Environment
- doPost() in main.js
- Dispatch layer: maps path to appropriate controller.
C. Controller Layer
- Validate input → call service → return response wrapper.
D. Service Layer
- Core business rules (auth, user, media management).
- On errors, call utils/email to send error notifications.
E. Repository Layer
- Uses SpreadsheetApp API to read/write Sheets.
- factory.repository selects the correct sheet (Auth, User, Media).
F. Data Storage
- Google Sheets (three tabs: auth, user, media).
G. External Google Services
- GmailApp (error emails)
- (Optional) DriveApp if storing actual file content—currently metadata only.

##### Architectural Patterns & Principles
- Layered architecture: Controllers → Services → Repositories → Sheets.
- Single Responsibility per module (validation, helpers, entities).
- Factory pattern for repository instantiation.
- Centralized error handling with email notifications.
- Environment-driven configuration (api keys, sheet IDs in src/_utils/environment.js).

##### Technologies & Frameworks
- Google Apps Script runtime & built-in services (SpreadsheetApp, GmailApp).
- clasp (local development & deployment tool).
- Vanilla JavaScript modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        Client["Client (HTTP POST JSON)"]:::external
    end

    %% API Layer
    Client -->|"POST JSON"| Main["doPost()"]:::api

    %% Validator Layer
    subgraph "Validator Layer"
        CommonV["_common.validator.js"]:::validator
        AuthV["auth.validator.js"]:::validator
        UserV["user.validator.js"]:::validator
        MediaV["media.validator.js"]:::validator
    end
    Main --> CommonV
    Main --> AuthV
    Main --> UserV
    Main --> MediaV

    %% Controller Layer
    subgraph "Controller Layer"
        AC["auth.controller.js"]:::controller
        UC["user.controller.js"]:::controller
        MC["media.controller.js"]:::controller
    end
    Main --> AC
    Main --> UC
    Main --> MC
    AC --> AuthV
    UC --> UserV
    MC --> MediaV

    %% Service Layer
    subgraph "Service Layer"
        AS["auth.service.js"]:::service
        US["user.service.js"]:::service
        MS["media.service.js"]:::service
    end
    AC -->|"validate → call service"| AS
    UC -->|"validate → call service"| US
    MC -->|"validate → call service"| MS

    %% Entity Layer
    subgraph "Entity Layer"
        CommonEntity["_common.entity.js"]:::entity
        AuthEntity["auth.entity.js"]:::entity
        UserEntity["user.entity.js"]:::entity
        MediaEntity["media.entity.js"]:::entity
    end
    AS --> AuthEntity
    US --> UserEntity
    MS --> MediaEntity

    %% Repository Layer
    subgraph "Repository Layer"
        Factory["factory.repository.js"]:::repo
    end
    AS -->|"data operations"| Factory
    US -->|"data operations"| Factory
    MS -->|"data operations"| Factory

    %% Data Storage
    subgraph "Data Storage"
        Sheets["Google Sheets"]:::db
    end
    Factory -->|"sheet CRUD via SpreadsheetApp"| Sheets

    %% Utility Layer
    subgraph "Utils Layer"
        Env["environment.js"]:::util
        AuthH["handle.auth.js"]:::util
        Token["token.auth.js"]:::util
        EmailUtil["send-error.email.js"]:::util
        CommonH["common.helper.js"]:::util
        BaseResp["base.response.js"]:::util
        ExResp["exception.response.js"]:::util
        ValidateH["handle.validate.js"]:::util
        HTTPE["http-status.enum.js"]:::util
        AuthE["auth.enum.js"]:::util
        MediaE["media.enum.js"]:::util
    end
    Env --> Clasp
    Env --> AppScript
    AS --> EmailUtil
    US --> EmailUtil
    MS --> EmailUtil
    EmailUtil --> Gmail["GmailApp"]:::google
    EmailUtil --> BaseResp
    EmailUtil --> ExResp

    %% Configuration
    subgraph "Config"
        Clasp[".clasp.json"]:::config
        AppScript["appsscript.json"]:::config
    end

    %% Styles
    classDef external fill:#FFF176,stroke:#333,stroke-width:1px
    classDef api fill:#42A5F5,stroke:#333,stroke-width:1px
    classDef validator fill:#AED581,stroke:#333,stroke-width:1px
    classDef controller fill:#64B5F6,stroke:#333,stroke-width:1px
    classDef service fill:#81C784,stroke:#333,stroke-width:1px
    classDef entity fill:#FFE082,stroke:#333,stroke-width:1px
    classDef repo fill:#FFB74D,stroke:#333,stroke-width:1px
    classDef db fill:#FB8C00,stroke:#333,stroke-width:1px
    classDef util fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef google fill:#FFEB3B,stroke:#333,stroke-width:1px
    classDef config fill:#B39DDB,stroke:#333,stroke-width:1px

    %% Click Events
    click Main "https://github.com/lkduy2602/svibox/blob/main/src/main.js"
    click CommonV "https://github.com/lkduy2602/svibox/blob/main/src/validator/_common.validator.js"
    click AuthV "https://github.com/lkduy2602/svibox/blob/main/src/validator/auth.validator.js"
    click UserV "https://github.com/lkduy2602/svibox/blob/main/src/validator/user.validator.js"
    click MediaV "https://github.com/lkduy2602/svibox/blob/main/src/validator/media.validator.js"
    click AC "https://github.com/lkduy2602/svibox/blob/main/src/controller/auth.controller.js"
    click UC "https://github.com/lkduy2602/svibox/blob/main/src/controller/user.controller.js"
    click MC "https://github.com/lkduy2602/svibox/blob/main/src/controller/media.controller.js"
    click AS "https://github.com/lkduy2602/svibox/blob/main/src/service/auth.service.js"
    click US "https://github.com/lkduy2602/svibox/blob/main/src/service/user.service.js"
    click MS "https://github.com/lkduy2602/svibox/blob/main/src/service/media.service.js"
    click CommonEntity "https://github.com/lkduy2602/svibox/blob/main/src/entity/_common.entity.js"
    click AuthEntity "https://github.com/lkduy2602/svibox/blob/main/src/entity/auth.entity.js"
    click UserEntity "https://github.com/lkduy2602/svibox/blob/main/src/entity/user.entity.js"
    click MediaEntity "https://github.com/lkduy2602/svibox/blob/main/src/entity/media.entity.js"
    click Factory "https://github.com/lkduy2602/svibox/blob/main/src/repository/factory.repository.js"
    click Env "https://github.com/lkduy2602/svibox/blob/main/src/_utils/environment.js"
    click AuthH "https://github.com/lkduy2602/svibox/blob/main/src/_utils/auth/handle.auth.js"
    click Token "https://github.com/lkduy2602/svibox/blob/main/src/_utils/auth/token.auth.js"
    click EmailUtil "https://github.com/lkduy2602/svibox/blob/main/src/_utils/email/send-error.email.js"
    click CommonH "https://github.com/lkduy2602/svibox/blob/main/src/_utils/helper/common.helper.js"
    click BaseResp "https://github.com/lkduy2602/svibox/blob/main/src/_utils/response/base.response.js"
    click ExResp "https://github.com/lkduy2602/svibox/blob/main/src/_utils/response/exception.response.js"
    click ValidateH "https://github.com/lkduy2602/svibox/blob/main/src/_utils/validate/handle.validate.js"
    click HTTPE "https://github.com/lkduy2602/svibox/blob/main/src/_utils/enum/http-status.enum.js"
    click AuthE "https://github.com/lkduy2602/svibox/blob/main/src/_utils/enum/auth.enum.js"
    click MediaE "https://github.com/lkduy2602/svibox/blob/main/src/_utils/enum/media.enum.js"
    click Clasp "https://github.com/lkduy2602/svibox/blob/main/.clasp.json"
    click AppScript "https://github.com/lkduy2602/svibox/blob/main/appsscript.json"
```
