# adobe/aio-cli-plugin-app-storage architecture

> Architecture diagram of the GitHub repository adobe/aio-cli-plugin-app-storage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adobe/aio-cli-plugin-app-storage
- Repository: https://github.com/adobe/aio-cli-plugin-app-storage

## Overview

##### Project type and purpose
- This is an open-source Node.js CLI plugin (“aio-cli-plugin-app-storage”) built on the oclif framework.
- Its purpose is to add “app state” commands to the Adobe I/O CLI, allowing users to list, get, put, delete, and view stats on key-value state storage.

##### Main architectural components
a. CLI entrypoint (bin/)
- bin/run.js & bin/dev.js: small wrappers that invoke oclif’s command dispatch.
- They bootstrap the plugin when a user types `aio app state …`.
b. CLI framework core (external)
- oclif (the Adobe CLI core) loads the plugin, parses arguments, locates the appropriate command class.
c. Command classes (src/commands/app/state/*.js)
- One class per operation: delete.js, get.js, list.js, put.js, stats.js.
- Each extends BaseCommand.js (handles common flags like `--json`, `--region`) and implements run() to call the state library.
d. State library (external dependency)
- @adobe/aio-lib-state: encapsulates HTTP/API calls to the Adobe State service. Commands delegate to it for all storage operations.
e. Configuration & constants (src/constants.js)
- Stores default region, TTL defaults, JSON‐output logic.
f. Testing & CI
- Unit tests (test/) verify each command’s behavior via Jest.
- End-to-end script (e2e/e2e.js) exercises the CLI binary against a live or mock service.
- GitHub workflows (.github/workflows/) automate linting, testing, publishing to NPM.

##### Relationships and data flow
1. User invokes CLI: `aio app state <command> [args]`
2. bin/run.js → oclif CLI core → plugin loader
3. oclif maps to the appropriate Command class in src/commands
4. Command.run():
- Parses flags & args (via BaseCommand).
- Calls a helper in @adobe/aio-lib-state (passing key, value, region, ttl).
5. aio-lib-state makes HTTP requests to Adobe’s state service API
6. API responds → library returns a JavaScript object
7. Command formats output (plain text or JSON) → writes to stdout
8. e2e or unit tests assert on exit code and stdout content
9. GitHub Actions ensure each step passes on push or PR, then auto-publish on release.

##### Architectural patterns & design principles
- Command pattern: each CLI command is an isolated class.
- Dependency inversion: commands depend on an abstraction (@adobe/aio-lib-state) instead of HTTP details.
- Single responsibility: BaseCommand handles common flags; each subclass handles only one operation.
- Modular plugins: the Adobe CLI core loads this plugin at runtime—easy to add/remove functionality.

##### Detailed callouts
- Flags parsing in BaseCommand (common across commands).
- Default region resolution (env var vs. amer).
- How TTL flag is passed into aio-lib-state for put command.
- Tests mocking the state library vs. e2e hitting the real service.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Local Code
    subgraph "Local Code"
        direction TB
        User(["User"]):::user
        Run(["bin/run.js"]):::entry
        Dev(["bin/dev.js"]):::entry
        Base(["BaseCommand.js"]):::base
        Const(["constants.js"]):::base
        subgraph "Command Classes"
            direction TB
            DeleteCmd(["delete.js"]):::cmd
            GetCmd(["get.js"]):::cmd
            ListCmd(["list.js"]):::cmd
            PutCmd(["put.js"]):::cmd
            StatsCmd(["stats.js"]):::cmd
        end
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        Oclif(["oclif CLI Core"]):::core
        LibState(["@adobe/aio-lib-state"]):::lib
    end

    %% External Service
    subgraph "External Service"
        direction TB
        StateAPI(["Adobe State Service API"]):::service
    end

    %% CI/CD
    subgraph "CI/CD"
        direction TB
        subgraph "Unit Tests"
            direction TB
            BaseTest(["BaseCommand.test.js"]):::test
            DeleteTest(["delete.test.js"]):::test
            GetTest(["get.test.js"]):::test
            ListTest(["list.test.js"]):::test
            PutTest(["put.test.js"]):::test
            StatsTest(["stats.test.js"]):::test
        end
        E2E(["e2e.js"]):::test
        subgraph "GitHub Workflows"
            direction TB
            NodeCI(["node.js.yml"]):::ci
            OnPushCI(["on-push-publish-to-npm.yml"]):::ci
            PrereleaseCI(["prerelease.yml"]):::ci
            ReleaseBranchCI(["release-branch.yml"]):::ci
            VersionBumpCI(["version-bump-publish.yml"]):::ci
            DailyCI(["daily.yml"]):::ci
            PullRequestCI(["pull_request.yml"]):::ci
        end
    end

    %% Connections
    User -->|"exec shell"| Run
    User -->|"exec shell"| Dev
    Run -->|"initialize plugin"| Oclif
    Dev -->|"initialize plugin"| Oclif
    Oclif -->|"instantiate + run()"| DeleteCmd
    Oclif -->|"instantiate + run()"| GetCmd
    Oclif -->|"instantiate + run()"| ListCmd
    Oclif -->|"instantiate + run()"| PutCmd
    Oclif -->|"instantiate + run()"| StatsCmd

    DeleteCmd -->|"extends + parse flags"| Base
    GetCmd -->|"extends + parse flags"| Base
    ListCmd -->|"extends + parse flags"| Base
    PutCmd -->|"extends + parse flags"| Base
    StatsCmd -->|"extends + parse flags"| Base

    DeleteCmd -->|"use defaults"| Const
    GetCmd -->|"use defaults"| Const
    ListCmd -->|"use defaults"| Const
    PutCmd -->|"use defaults"| Const
    StatsCmd -->|"use defaults"| Const

    DeleteCmd -->|"calls state lib"| LibState
    GetCmd -->|"calls state lib"| LibState
    ListCmd -->|"calls state lib"| LibState
    PutCmd -->|"calls state lib"| LibState
    StatsCmd -->|"calls state lib"| LibState

    LibState -->|"HTTP request/response"| StateAPI
    StateAPI -->|"HTTP response"| LibState
    LibState -->|"returns data"| DeleteCmd
    LibState -->|"returns data"| GetCmd
    LibState -->|"returns data"| ListCmd
    LibState -->|"returns data"| PutCmd
    LibState -->|"returns data"| StatsCmd

    DeleteCmd -->|"writes to stdout"| User
    GetCmd -->|"writes to stdout"| User
    ListCmd -->|"writes to stdout"| User
    PutCmd -->|"writes to stdout"| User
    StatsCmd -->|"writes to stdout"| User

    %% Tests
    BaseTest -->|tests| Base
    DeleteTest -->|tests| DeleteCmd
    GetTest -->|tests| GetCmd
    ListTest -->|tests| ListCmd
    PutTest -->|tests| PutCmd
    StatsTest -->|tests| StatsCmd
    E2E -->|executes| Run

    %% CI flows
    NodeCI -->|runs| BaseTest
    NodeCI -->|runs| DeleteTest
    NodeCI -->|runs| GetTest
    NodeCI -->|runs| ListTest
    NodeCI -->|runs| PutTest
    NodeCI -->|runs| StatsTest
    OnPushCI -->|triggers| NodeCI
    PrereleaseCI -->|triggers| OnPushCI
    ReleaseBranchCI -->|triggers| PrereleaseCI
    VersionBumpCI -->|triggers| ReleaseBranchCI
    DailyCI -->|triggers| NodeCI
    PullRequestCI -->|triggers| NodeCI

    %% Click Events
    click Run "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/bin/run.js"
    click Dev "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/bin/dev.js"
    click Base "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/src/BaseCommand.js"
    click Const "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/src/constants.js"
    click DeleteCmd "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/src/commands/app/state/delete.js"
    click GetCmd "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/src/commands/app/state/get.js"
    click ListCmd "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/src/commands/app/state/list.js"
    click PutCmd "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/src/commands/app/state/put.js"
    click StatsCmd "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/src/commands/app/state/stats.js"
    click BaseTest "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/test/BaseCommand.test.js"
    click DeleteTest "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/test/commands/app/state/delete.test.js"
    click GetTest "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/test/commands/app/state/get.test.js"
    click ListTest "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/test/commands/app/state/list.test.js"
    click PutTest "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/test/commands/app/state/put.test.js"
    click StatsTest "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/test/commands/app/state/stats.test.js"
    click E2E "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/e2e/e2e.js"
    click NodeCI "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/.github/workflows/node.js.yml"
    click OnPushCI "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/.github/workflows/on-push-publish-to-npm.yml"
    click PrereleaseCI "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/.github/workflows/prerelease.yml"
    click ReleaseBranchCI "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/.github/workflows/release-branch.yml"
    click VersionBumpCI "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/.github/workflows/version-bump-publish.yml"
    click DailyCI "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/.github/workflows/daily.yml"
    click PullRequestCI "https://github.com/adobe/aio-cli-plugin-app-storage/blob/main/.github/workflows/pull_request.yml"

    %% Styles
    classDef entry fill:#a2f5a2,stroke:#333,stroke-width:1px
    classDef core fill:#a2d2f5,stroke:#333,stroke-width:1px
    classDef cmd fill:#f5d76e,stroke:#333,stroke-width:1px
    classDef base fill:#f7e8a4,stroke:#333,stroke-width:1px
    classDef lib fill:#f5b27a,stroke:#333,stroke-width:1px
    classDef service fill:#f28b82,stroke:#333,stroke-width:1px
    classDef test fill:#cccccc,stroke:#333,stroke-width:1px
    classDef ci fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef user fill:#ffffff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
