# stackosofficial/ai-access-package architecture

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

- Interactive diagram: https://gitdiagram.com/stackosofficial/ai-access-package
- Repository: https://github.com/stackosofficial/ai-access-package

## Overview

##### Project type and purpose
- This is an NPM-distributed, TypeScript-based middleware library (“sky-ai-accesspoint”) that you embed into an Express server to provide a secure AI endpoint.
- Its purpose is to expose a single HTTP API (POST /natural-request) that enforces NFT-based access control, tracks and updates user balances in Firebase, and proxies requests to an OpenAI model and Skynet’s blockchain infrastructure.

##### File structure
- Top level: Dockerfile, GitHub workflows, package.json, src/ (TypeScript sources), lib/ (compiled JS + typings).
- src/ contains core modules:
- init.ts – bootstrapper (initAIAccessPoint)
- balanceRunMain.ts – orchestrator class
- balanceExtractService.ts – cost-parsing logic
- serverBalanceDatabaseService.ts – Firebase reads/writes
- databaseWriterExecution.ts, timeIntervalExecution.ts, nonReentrantExecution.ts, mutex.ts – background-job and concurrency helpers
- middleware/ – Express middleware: parseAuth, auth (protect), checkBalance
- envConfig.ts, utils.ts, types/ – config and type definitions
- Configuration: tsconfig.json, .npmrc, Dockerfile for containerization, GitHub Actions for CI/CD.

##### README for extra insights
- Environment variables: JSON_RPC_PROVIDER, FIREBASE_*, OPENAI_API_KEY, etc.
- Usage:
- Developer calls initAIAccessPoint(env, SkyMainNodeJS, expressApp, runNaturalFunction, runUpdate)
- initAIAccessPoint registers middleware and endpoint(s), returns BalanceRunMain instance.
- runNaturalFunction uses balanceRunMain.callAIModel() to hit OpenAI.
- Middleware chain enforces authentication, NFT ownership, balance checks.
- Cost management: balanceRunMain.addCost() writes to Firebase.

##### Be detailed
- Middleware components, the initAIAccessPoint bootstrap, the BalanceRunMain methods, scheduler modules, and each external integration.
- Don’t hesitate to break out sub-components (for example, separate the scheduler into timeIntervalExecution + databaseWriterExecution).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Client["HTTP Client"]:::external

    %% Bootstrapper
    Init["initAIAccessPoint()"]:::core

    %% API Layer
    subgraph "API Layer"
        direction TB
        ParseAuth["parseAuth"]:::api
        AuthGuard["auth (NFT & Auth Guard)"]:::api
        CheckBalance["checkBalance"]:::api
        Handler["runNaturalFunction\n(POST /natural-request)"]:::api
    end

    %% Core Services
    subgraph "Core Services"
        direction TB
        BalanceCore["BalanceRunMain"]:::core
        BalanceExtract["balanceExtractService"]:::core
        FirebaseService["serverBalanceDatabaseService"]:::core
    end

    %% Helpers
    subgraph "Helpers & Concurrency"
        direction TB
        Scheduler["timeIntervalExecution"]:::helper
        JobExecutor["databaseWriterExecution"]:::helper
        NonReentrant["nonReentrantExecution"]:::helper
        Mutex["mutex"]:::helper
        EnvConfig["envConfig"]:::helper
        Utils["utils"]:::helper
        Types["types"]:::helper
    end

    %% External & Data
    subgraph "Data & External Services"
        direction TB
        Firestore["Firebase Firestore"]:::data
        OpenAI["OpenAI API"]:::external
        SkyNode["SkyMainNodeJS\n(Blockchain)"]:::external
    end

    %% Flows
    Client -->|"POST /natural-request"| ParseAuth
    ParseAuth --> AuthGuard
    AuthGuard --> CheckBalance
    CheckBalance --> Handler
    Handler -->|"callAIModel()"| BalanceCore
    BalanceCore -->|"parseCost()"| BalanceExtract
    BalanceCore -->|"addCost()/update()"| FirebaseService
    BalanceCore -->|"checkNFT()/contractCall"| SkyNode
    BalanceCore -->|"chat/completion"| OpenAI

    Scheduler --> JobExecutor
    JobExecutor -->|"update()"| BalanceCore
    BalanceCore --> Firestore
    FirebaseService --> Firestore

    %% Bootstrapper Integration
    Client -.-> Init
    Init --> ParseAuth
    Init --> BalanceCore

    %% Helper Usage
    BalanceCore --> NonReentrant
    BalanceCore --> Mutex
    BalanceCore --> EnvConfig
    BalanceCore --> Utils
    BalanceCore --> Types
    Scheduler --> EnvConfig
    JobExecutor --> NonReentrant

    %% Click Events
    click Init "https://github.com/stackosofficial/ai-access-package/blob/master/src/init.ts"
    click BalanceCore "https://github.com/stackosofficial/ai-access-package/blob/master/src/balanceRunMain.ts"
    click BalanceExtract "https://github.com/stackosofficial/ai-access-package/blob/master/src/balanceExtractService.ts"
    click FirebaseService "https://github.com/stackosofficial/ai-access-package/blob/master/src/serverBalanceDatabaseService.ts"
    click JobExecutor "https://github.com/stackosofficial/ai-access-package/blob/master/src/databaseWriterExecution.ts"
    click Scheduler "https://github.com/stackosofficial/ai-access-package/blob/master/src/timeIntervalExecution.ts"
    click NonReentrant "https://github.com/stackosofficial/ai-access-package/blob/master/src/nonReentrantExecution.ts"
    click Mutex "https://github.com/stackosofficial/ai-access-package/blob/master/src/mutex.ts"
    click ParseAuth "https://github.com/stackosofficial/ai-access-package/blob/master/src/middleware/parseAuth.ts"
    click AuthGuard "https://github.com/stackosofficial/ai-access-package/blob/master/src/middleware/auth.ts"
    click CheckBalance "https://github.com/stackosofficial/ai-access-package/blob/master/src/middleware/checkBalance.ts"
    click EnvConfig "https://github.com/stackosofficial/ai-access-package/blob/master/src/envConfig.ts"
    click Utils "https://github.com/stackosofficial/ai-access-package/blob/master/src/utils.ts"
    click Types "https://github.com/stackosofficial/ai-access-package/blob/master/src/types/types.ts"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#3498DB,color:#000;
    classDef core fill:#D0FFD8,stroke:#2ECC71,color:#000;
    classDef helper fill:#FFF5D6,stroke:#F1C40F,color:#000;
    classDef data fill:#FFE0B2,stroke:#E67E22,color:#000;
    classDef external fill:#F2F2F2,stroke:#7F8C8D,color:#000;
```
