# sunhome243/ai_led_backend architecture

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

- Interactive diagram: https://gitdiagram.com/sunhome243/ai_led_backend
- Repository: https://github.com/sunhome243/ai_led_backend

## Overview

##### Project Type and Purpose
- The project is an Infrastructure as Code (IaC) repository to deploy an AI-powered LED control system. It integrates AWS services (Lambda, API Gateway, DynamoDB, S3), Terraform, and external AI (Google Gemini AI) along with hardware integration (Arduino/IR-based LED controllers).
- The README clarifies that this backend system works with a separate frontend repository and uses multiple Lambda functions for processing audio and pattern information, then applies AI to generate personalized LED lighting configurations.

##### Analysis of the File Structure
- Top-level directories include configuration directories (.github with GitHub Actions workflows, modules for Terraform code, lambda containing AWS Lambda function sources, and public assets for images).
- The "lambda" directory shows clear subdirectories for different processing functions:
- audio_to_ai: handling audio input.
- pattern_to_ai: handling pattern analysis and “surprise me” functionality.
- result_save_send: task to process AI output, save results, and send commands.
- websocket: managing connections.
- Terraform files such as main.tf, providers.tf, variables.tf, and modules (compute, database, iam, networking, websocket) point to a modularized deployment structure using Terraform with separate concerns for networking, compute (Lambda functions), database services, and IAM policies.
- There is also a build_layer.sh and a lambda_layer.tf file, which indicate the presence of Lambda layers for dependency management.

##### Relationships and Interactions
- The Frontend Application sends user input (audio files, pattern data, UUID/PIN) to API Gateway.
- API Gateway routes the requests to the respective Lambda functions.
- Lambda functions process the data – invoking Google Gemini AI for analysis and then sending results to result_save_send.
- The result_save_send Lambda function integrates with DynamoDB (storing AI responses and mappings) and S3 (archiving data), and then sends IR commands back through API Gateway’s WebSocket channel to IoT devices.
- WebSocket connections are managed by dedicated Lambda functions, ensuring real-time communication between the backend and the IoT devices.

##### Architectural Patterns and Design Principles
- Serverless architecture is prominent, with AWS Lambda central to the design.
- Modular IaC using Terraform:
- Modules are organized by concern (compute, database, networking, IAM, websocket) for scalability and clarity.
- Separation of Concerns:
- Distinct Lambda functions handle dedicated processing tasks (audio, pattern, result management, connection management).
- External Service Integration:
- AI analysis done through Google Gemini shows separation of core functionality from third-party processing.
- Real-time Communication:
- Use of API Gateway’s WebSocket for push-based device communications.
- Security and Extensibility:
- Simple UUID and PIN-based authentication is implemented with room to improve security in the future.
- Terraform sensitive variables and modularization points for future enhancements.

- Component has a clear label along with the specific role it plays.
- Use annotations or legends to highlight the architectural patterns, such as “Serverless Processing,” “Real-time Communication,” or “Modular IaC.”
- Including a brief description or note next to each component explaining any critical technical details (for example, “audio_to_ai Lambda calls Gemini AI for emotional analysis” or “WebSocket connection managed by connection_manager Lambda”).

## Diagram (Mermaid)

```mermaid
graph TD
    A["Frontend Application"]:::frontend
    B["API Gateway (REST & WebSocket)"]:::gateway
    C["AWS Lambda: audio_to_ai"]:::lambda
    D["AWS Lambda: pattern_to_ai"]:::lambda
    E["AWS Lambda: result_save_send"]:::lambda
    F["AWS Lambda: connection_manager"]:::lambda
    G["Google Gemini AI"]:::external
    H["DynamoDB"]:::database
    I["S3 Bucket"]:::database
    J["Arduino/LED Controller"]:::hardware

    %% Data Flow
    A -->|"REST"| B
    B -->|"routes"| C
    B -->|"routes"| D
    B -->|"routes"| E
    B -->|"WS"| F

    C -->|"calls"| G
    D -->|"calls"| G

    E -->|"savesTo"| H
    E -->|"archivesTo"| I
    E -->|"sendsViaWS"| B

    B -->|"WSmsg"| J

    %% Terraform Modules Subgraph
    subgraph "Terraform Modules"
        K["Compute (Lambda)"]:::infra
        L["Networking (API Gateway)"]:::infra
        M["Database (DynamoDB & S3)"]:::infra
        N["IAM Policies"]:::infra
        O["Websocket Setup"]:::infra
    end

    %% Terraform relationships
    K --- C
    K --- D
    K --- E
    K --- F
    L --- B
    M --- H
    M --- I
    O --- F
    O --- B
    N --- K
    N --- L
    N --- M
    N --- O

    %% Lambda Layer for Dependency Management
    P["Lambda Layer (Dependency)"]:::infra
    P --- C
    P --- D
    P --- E
    P --- F

    %% Click Events
    click C "https://github.com/sunhome243/ai_led_backend/tree/main/lambda/audio_to_ai/"
    click D "https://github.com/sunhome243/ai_led_backend/tree/main/lambda/pattern_to_ai/"
    click E "https://github.com/sunhome243/ai_led_backend/tree/main/lambda/result_save_send/"
    click F "https://github.com/sunhome243/ai_led_backend/tree/main/lambda/websocket/"
    click B "https://github.com/sunhome243/ai_led_backend/blob/main/modules/networking/apiGateway.tf"
    click K "https://github.com/sunhome243/ai_led_backend/tree/main/modules/compute/"
    click M "https://github.com/sunhome243/ai_led_backend/tree/main/modules/database/"
    click N "https://github.com/sunhome243/ai_led_backend/tree/main/modules/iam/"
    click O "https://github.com/sunhome243/ai_led_backend/tree/main/modules/websocket/"
    click P "https://github.com/sunhome243/ai_led_backend/blob/main/lambda_layer.tf"
    click J "https://github.com/sunhome243/ai_led_backend/blob/main/hardware.ino"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#000,stroke-width:1px;
    classDef gateway fill:#F7DC6F,stroke:#000,stroke-width:1px;
    classDef lambda fill:#82E0AA,stroke:#000,stroke-width:1px;
    classDef external fill:#F5B7B1,stroke:#000,stroke-width:1px;
    classDef database fill:#D2B4DE,stroke:#000,stroke-width:1px;
    classDef infra fill:#FAD7A0,stroke:#000,stroke-width:1px;
    classDef hardware fill:#A3E4D7,stroke:#000,stroke-width:1px;
```
