# carlsamma/sunopromptlastfmapi architecture

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

- Interactive diagram: https://gitdiagram.com/carlsamma/sunopromptlastfmapi
- Repository: https://github.com/carlsamma/sunopromptlastfmapi

## Overview

##### Project Type and Purpose
- This is a full-stack AI Studio web application.
- The root contains a Vite-powered React/TypeScript front-end (`index.html`, `index.tsx`, `vite.config.ts`, `src/components`, etc.) and a standalone Node/TypeScript microservice in `multi-api-server/` that acts as the back-end API layer.
- The app’s goal is to provide an interactive UI (including a Last.fm integration component) that calls out to AI services (e.g., Google Gemini) via the micro-service.

##### File Structure Analysis
- Top-level directories/files
– `.env` / `.env.local` – stores `GEMINI_API_KEY` and other secrets
– `index.html` + `index.tsx` + `vite.config.ts` + `src/` – front-end UI code
– `multi-api-server/` – back-end microservice, with its own `src/index.ts`, `logger.ts`, config examples, and setup guides
– `metadata.json` – likely front-end metadata for AI-config or prompt definitions
- Patterns and Configs
– Front-end: React + TypeScript + Vite
– Back-end: Node.js + TypeScript (Express or similar HTTP server), custom logger, config-driven API connectors
– No dedicated database folder; state likely ephemeral or uses third-party APIs only

##### README Insights
- Describes how to install dependencies (`npm install`), set `GEMINI_API_KEY` in `.env.local`, and run both front-end (`npm run dev`) and back-end (via `multi-api-server/SETUP_GUIDE.md`).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Front-end Layer
    subgraph "Front-end"
        direction TB
        Browser["Browser / React UI"]:::frontend
        Vite["Vite Dev Server / Static Host"]:::frontend
        subgraph "Front-end Code"
            direction TB
            HTML["index.html"]:::frontend
            IndexTSX["index.tsx"]:::frontend
            ViteConfig["vite.config.ts"]:::frontend
            TSConfig["tsconfig.json"]:::frontend
            PackageRoot["package.json"]:::frontend
            ReactComp["LastFmIntegration.tsx"]:::frontend
            MCPClient["mcp-client.ts"]:::frontend
            Metadata["metadata.json"]:::config
        end
        Env[".env / .env.local"]:::config
    end

    %% Back-end Layer
    subgraph "Back-end Microservice"
        direction TB
        MultiApiDir["multi-api-server/"]:::backend
        BEpkg["package.json"]:::backend
        BETs["tsconfig.json"]:::backend
        BEIndex["src/index.ts"]:::backend
        BELogger["src/logger.ts"]:::backend
        BEConfigExample["mcp-config-example.json"]:::backend
        BESetupGuide["SETUP_GUIDE.md"]:::backend
        BELoggingGuide["LOGGING_GUIDE.md"]:::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Gemini["Google Gemini API"]:::external
        LastfmAPI["Last.fm API"]:::external
    end

    %% Data Flow
    Browser -->|"Loads assets"| Vite
    Vite -->|"Serves Static Bundles"| Browser
    Browser -->|"User triggers React Component"| MCPClient
    MCPClient -->|"HTTP POST /mcp/generate or /lastfm"| BEIndex
    BEIndex -->|"Logs request"| BELogger
    BEIndex -->|"Reads config"| BEConfigExample
    BEIndex -->|"Reads secrets"| Env
    BEIndex -->|"Calls Google Gemini"| Gemini
    BEIndex -->|"Calls Last.fm"| LastfmAPI
    Gemini -->|"Response"| BEIndex
    LastfmAPI -->|"Response"| BEIndex
    BEIndex -->|"API Response"| Browser

    %% Click Events
    click HTML "https://github.com/carlsamma/sunopromptlastfmapi/blob/sunoMCPS/index.html"
    click IndexTSX "https://github.com/carlsamma/sunopromptlastfmapi/blob/sunoMCPS/index.tsx"
    click ViteConfig "https://github.com/carlsamma/sunopromptlastfmapi/blob/sunoMCPS/vite.config.ts"
    click TSConfig "https://github.com/carlsamma/sunopromptlastfmapi/blob/sunoMCPS/tsconfig.json"
    click PackageRoot "https://github.com/carlsamma/sunopromptlastfmapi/blob/sunoMCPS/package.json"
    click ReactComp "https://github.com/carlsamma/sunopromptlastfmapi/blob/sunoMCPS/src/components/LastFmIntegration.tsx"
    click MCPClient "https://github.com/carlsamma/sunopromptlastfmapi/blob/sunoMCPS/src/mcp-client.ts"
    click Metadata "https://github.com/carlsamma/sunopromptlastfmapi/blob/sunoMCPS/metadata.json"
    click Env "https://github.com/carlsamma/sunopromptlastfmapi/blob/sunoMCPS/.env"
    click MultiApiDir "https://github.com/carlsamma/sunopromptlastfmapi/tree/sunoMCPS/multi-api-server/"
    click BEpkg "https://github.com/carlsamma/sunopromptlastfmapi/blob/sunoMCPS/multi-api-server/package.json"
    click BETs "https://github.com/carlsamma/sunopromptlastfmapi/blob/sunoMCPS/multi-api-server/tsconfig.json"
    click BEIndex "https://github.com/carlsamma/sunopromptlastfmapi/blob/sunoMCPS/multi-api-server/src/index.ts"
    click BELogger "https://github.com/carlsamma/sunopromptlastfmapi/blob/sunoMCPS/multi-api-server/src/logger.ts"
    click BEConfigExample "https://github.com/carlsamma/sunopromptlastfmapi/blob/sunoMCPS/multi-api-server/mcp-config-example.json"
    click BESetupGuide "https://github.com/carlsamma/sunopromptlastfmapi/blob/sunoMCPS/multi-api-server/SETUP_GUIDE.md"
    click BELoggingGuide "https://github.com/carlsamma/sunopromptlastfmapi/blob/sunoMCPS/multi-api-server/LOGGING_GUIDE.md"

    %% Styling
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef config fill:#FFFFE0,stroke:#000,stroke-width:1px;
```
