# code100x/mobile-magic architecture

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

- Interactive diagram: https://gitdiagram.com/code100x/mobile-magic
- Repository: https://github.com/code100x/mobile-magic

## Overview

##### Project Type and Purpose
- The file tree indicates a multi-application (or microservices-like) project with clearly separated apps including “frontend” (likely a Next.js React application), “primary-backend” (responsible for the main API/server-side logic), “worker-orchestrator” (task scheduling/scaling logic for worker processes), “worker” (performing background tasks, such as parsing, handling system prompts, etc.), and “code-server” (which might be an embedded development environment running in a container).
- Additional “packages” provide shared functionality such as common utilities, database (with Prisma migrations), Redis integration (likely for caching or messaging), and shared configuration (for ESLint and TypeScript).
- The README tasks highlight features like orchestrating workers through ASGs, scaling, load balancing between workers (via a dedicated load balancer), UI improvements, asynchronous handling of tasks (npm install queue), and possible S3 backups. This further confirms that this is a full-stack distributed system with distinct UI, API/backend, background worker, and infrastructure components.

##### Analyzing the File Structure
- The top-level “apps” folder is divided into multiple service directories. Each app contains its own README, package.json, and TypeScript configs. This implies services are developed and deployed somewhat independently.
- “apps/frontend” includes a Next.js application with separate routing (app/page.tsx, project-specific files) and many components indicating a clear separation of presentation and UI logic.
- “apps/primary-backend” appears to be the central API server handling primary application logic.
- “apps/worker” and “apps/worker-orchestrator” suggest background processing and scaling logic for workers. The orchestrator likely manages worker lifecycle (scaling up/draining) and consequently communicates with both the workers and (possibly) cloud services.
- The “packages” folder shows shared utilities. “packages/db” uses Prisma managing migrations, pointing out a relational database is in use. “packages/redis” indicates caching or message passing functionality. Shared configuration packages (eslint, typescript) help ensure consistency across services.

##### Key Elements
a. Main Components:
- Frontend: The Next.js application (apps/frontend) managing user interactions, UI rendering, and possibly connecting to the LLM.
- Primary Backend: The API server (apps/primary-backend) that processes user requests, handles business logic, and coordinates with other services.
- Worker Orchestrator: The service (apps/worker-orchestrator) responsible for monitoring worker states and scaling operations based on idle workers & ASG integration.
- Worker: The dedicated background service (apps/worker) performing tasks like file parsing and handling system prompts.
- Code Server: A Dockerized service (apps/code-server) that might provide a remote coding environment for development or project-specific editing.
- Shared Modules: Packages for common utilities, database access (via Prisma), and Redis for state management or messaging.
- External Infrastructure: Components like load balancer (mentioned in README for routing requests to the respective worker), potential S3 backup services, and ASGs for scaling infrastructure.

b. Relationships and Interactions:
- The Frontend communicates with the Primary Backend via REST or GraphQL APIs to submit requests and receive responses (including sending user changes which need to be recognized by the LLM).
- The Primary Backend interacts with the database (via packages/db) for persistent storage and possibly with Redis (via packages/redis) for caching or message queueing.
- The Primary Backend may also dispatch tasks to the Worker through the Worker Orchestrator if operations require background processing. The orchestrator monitors worker availability and scales them.
- The Load Balancer routes incoming requests (e.g., from id.worker.100xdevs.com) to the appropriate worker service instance.
- The Code Server (running in its own container) probably serves development or code-editing related tasks, interacting with either the frontend or backend as needed.
- Shared packages (common, types, utilities) are consumed across all services to maintain consistency.

c. Architectural Patterns & Design Principles:
- Microservices / Modular architecture: Each major function is in a separate service.
- Separation of concerns: UI (frontend), business logic (primary-backend), background processing (worker), and orchestration (worker-orchestrator) are all decoupled.
- Shared libraries: Use of a “packages” folder to manage common code and configurations.
- Infrastructure as Code: Dockerfile for code-server, the use of Prisma for migrations, and environment variables (noted in worker-orchestrator’s .env.example).

d. Relevant Technologies, Frameworks, and Libraries:
- Next.js (React) for the frontend.
- TypeScript for type safety across services.
- Prisma for database interaction and migrations.
- Redis for caching or messaging.
- Docker (Dockerfile in code-server) for containerization.
- Node.js environment (as inferred by package.json files and TypeScript setups) for backend and worker processes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Services
    subgraph "Application Services"
        FE["Frontend (Next.js)"]:::frontend
        BE["Primary Backend (API Server)"]:::backend
        WO["Worker Orchestrator"]:::orchestrator
        W["Worker (Background Tasks)"]:::worker
        CS["Code Server (Dev Container)"]:::dev
    end

    %% Shared Modules
    subgraph "Shared Modules"
        SU["Shared Utilities/Commons"]:::shared
        DB["Database (Prisma)"]:::database
        RI["Redis Integration"]:::cache
    end

    %% Infrastructure / External Components
    subgraph "Infrastructure / External"
        LB["Load Balancer"]:::external
        ASG["ASG (Auto Scaling)"]:::external
        S3["S3 Backup"]:::external
    end

    %% Connections between Application Services
    FE -->|"API_call"| BE
    BE -->|"Dispatch_tasks"| WO
    WO -->|"Schedule_tasks"| W
    W -->|"Return_results"| BE
    CS ---|"Integration"| BE
    CS ---|"Integration"| FE

    %% Connections with Shared Modules
    FE -->|"Uses_shared"| SU
    BE -->|"Uses_shared"| SU
    WO -->|"Uses_shared"| SU
    W  -->|"Uses_shared"| SU
    CS -->|"Uses_shared"| SU

    %% Connections with Shared Infrastructure
    BE -->|"CRUD_operations"| DB
    BE -->|"Cache/Messaging"| RI

    %% Infrastructure / External Interactions
    LB -->|"Route_requests"| W
    WO -->|"Scale_via"| ASG
    ASG -->|"Provisions"| W
    BE -->|"Backup_trigger"| S3

    %% Click Events
    click FE "https://github.com/code100x/mobile-magic/tree/main/apps/frontend"
    click BE "https://github.com/code100x/mobile-magic/tree/main/apps/primary-backend"
    click WO "https://github.com/code100x/mobile-magic/tree/main/apps/worker-orchestrator"
    click W "https://github.com/code100x/mobile-magic/tree/main/apps/worker"
    click CS "https://github.com/code100x/mobile-magic/tree/main/apps/code-server"
    click SU "https://github.com/code100x/mobile-magic/tree/main/packages/common"
    click DB "https://github.com/code100x/mobile-magic/tree/main/packages/db"
    click RI "https://github.com/code100x/mobile-magic/tree/main/packages/redis"

    %% Styles
    classDef frontend fill:#bbf,stroke:#333,stroke-width:2px;
    classDef backend fill:#fdd,stroke:#333,stroke-width:2px;
    classDef orchestrator fill:#ffd,stroke:#333,stroke-width:2px;
    classDef worker fill:#dfd,stroke:#333,stroke-width:2px;
    classDef dev fill:#eef,stroke:#333,stroke-width:2px;
    classDef database fill:#f9f,stroke:#333,stroke-width:2px;
    classDef cache fill:#cff,stroke:#333,stroke-width:2px;
    classDef shared fill:#fcf,stroke:#333,stroke-width:2px;
    classDef external fill:#ccc,stroke:#333,stroke-width:2px;
```
