# rayaan-khan428/beacon architecture

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

- Interactive diagram: https://gitdiagram.com/rayaan-khan428/beacon
- Repository: https://github.com/rayaan-khan428/beacon

## Overview

##### Project type and purpose
- This is a multi-component full-stack application.
- “ios_app” is an iOS SwiftUI mobile client (“BeaconAI”).
- “website” is a Next.js/React marketing/web client.
- “backend” is a Python service (likely REST/GraphQL API).
- “lambda” contains a zipped Python AWS Lambda deployment (with Twilio and other dependencies) for serverless workflows and webhooks.
- Purpose (inferred): BeaconAI mobile and web clients interact with a core Python backend, which delegates certain async or telephony tasks to AWS Lambda functions (e.g., via Twilio), plus a public website.

##### File structure
- Top-level directories:
- backend/venv – Python virtual environment for the main API.
- ios_app/BeaconAI – Xcode project implementing the mobile UI and data models (Item.swift, OnboardingView.swift, etc.).
- lambda/ – all Python dependencies and the “lambda_function.py” entry point packaged for AWS Lambda. Many Twilio SDK modules are present.
- website/ – Next.js (app/, components/, lib/) with TailwindCSS, TypeScript, and configuration files.
- Patterns and config:
- backend/ likely hosts your core API (no code shown, but venv suggests Flask, FastAPI, or Django).
- lambda/ contains a self-contained deployment package (third-party libs + your function).
- website/ is a standard React/Next.js monorepo layout.
- No explicit infrastructure-as-code files in root (e.g., Terraform), but assume AWS SAM/CloudFormation elsewhere.

##### README
- README is empty, so we rely on conventions and directory names. The “BeaconAI” branding signals a location/beacon-related AI offering with telephony or messaging integrations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        IOSApp["iOS Mobile Client<br/>(SwiftUI)"]:::frontend
        WebApp["Web Client<br/>(Next.js + TailwindCSS)"]:::frontend
    end

    %% API Gateway / Load Balancer
    APIGW["API Gateway / Load Balancer"]:::backend

    %% Core Backend
    BackendAPI["Core Backend API<br/>(Python Service)"]:::backend
    DB["Database<br/>(Amazon RDS / DynamoDB)"]:::database

    %% Serverless Layer
    subgraph "Serverless Functions"
        LambdaFunction["AWS Lambda<br/>(lambda_function.py)"]:::serverless
        LambdaDeps["Lambda Dependencies<br/>(Twilio SDK, etc.)"]:::serverless
        LambdaArchive["Deployment Package<br/>(lambda_deployment.zip)"]:::serverless
    end

    %% External Services
    Auth["Auth Provider<br/>(JWT)"]:::external
    APNs["APNs / Push Notifications"]:::external
    TwilioAPI["Twilio REST API"]:::external

    %% Connections - Front to API
    IOSApp -->|"HTTPS (REST/GraphQL)"| APIGW
    WebApp -->|"HTTPS (REST/GraphQL)"| APIGW

    %% API Gateway to Backend
    APIGW -->|"Forward Requests"| BackendAPI

    %% Backend to Database
    BackendAPI -->|"DB Queries"| DB

    %% Backend to Serverless
    BackendAPI -->|"Invoke Lambda (AWS SDK)"| LambdaFunction

    %% Backend Push Notifications and Auth
    BackendAPI -->|"Push Notifications"| APNs
    BackendAPI -->|"Auth Validation"| Auth

    %% Lambda internals
    LambdaFunction -->|"Uses Dependencies"| LambdaDeps
    LambdaFunction -->|"Reads Archive"| LambdaArchive
    LambdaFunction -->|"Send SMS/Voice"| TwilioAPI

    %% Styles
    classDef frontend fill:#f9daff,stroke:#333,stroke-width:1px
    classDef backend fill:#d0e7ff,stroke:#333,stroke-width:1px
    classDef database fill:#ffe7a8,stroke:#333,stroke-width:1px
    classDef serverless fill:#d4ffda,stroke:#333,stroke-width:1px
    classDef external fill:#ffd4d4,stroke:#333,stroke-width:1px

    %% Click Events
    click IOSApp "https://github.com/rayaan-khan428/beacon/tree/main/ios_app/BeaconAI"
    click WebApp "https://github.com/rayaan-khan428/beacon/tree/main/website"
    click BackendAPI "https://github.com/rayaan-khan428/beacon/tree/main/backend/venv"
    click LambdaFunction "https://github.com/rayaan-khan428/beacon/blob/main/lambda/lambda_function.py"
    click LambdaDeps "https://github.com/rayaan-khan428/beacon/tree/main/lambda/twilio"
    click LambdaArchive "https://github.com/rayaan-khan428/beacon/blob/main/lambda/lambda_deployment.zip"
```
