# antispace-ai/aios architecture

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

- Interactive diagram: https://gitdiagram.com/antispace-ai/aios
- Repository: https://github.com/antispace-ai/aios

## Overview

##### Project Type and Purpose
- This repository is a monorepo of example “apps” (plugins) built for the Antispace AIOS (Artificially Intelligent Operating System).
- Its purpose is to demonstrate, via multiple sample projects (GitHub, Linear, Slack, Spotify, Wallpaper Generator, Wikipedia, UI Components), how to structure and deploy AI‐powered web apps that hook into the AIOS platform.

##### File Structure Analysis
- Top level:
- docs/ – static assets (logos, SVGs) and system documentation references
- examples/ – each subfolder is a standalone AIOS app scaffold
- Each example app under examples/<app-name>/src/ typically follows this layout:
- ai/ – AI logic and “actions” modules
- manifest/ – definitions of platform‐exposed serverless functions
- ui/ – React components (page.tsx and widget.tsx) for the browser interface
- routes/ (where present) – HTTP endpoints (e.g., OAuth callbacks)
- util/ or config/ or db/ – helper modules (API wrappers, database connectors, config files)
- Some apps (e.g., wallpaper-generator) include a database schema, migration scripts, and an ORM config (Drizzle).

##### Key Insights from README
- The repo is part of the Antispace AIOS Labs: a framework/CLI that loads these “apps” into an AIOS environment.
- Apps are deployed as manifest‐driven serverless functions plus static UI assets.
- The development model encourages minimal boilerplate, clear separation of concerns, and integration with external services via actions.

##### Components
a. Antispace AIOS Platform
- CLI / Runtime Environment – orchestrates app registration, routing, and AIOS shell
- Core AI Engine – processes user messages, invokes actions, returns results to UI
b. Example App (generic template)
- UI Layer (Browser) – React page.tsx + widget.tsx loaded into AIOS shell
- Manifest Functions – serverless entrypoints defined in src/manifest/index.ts
- AI Module – src/ai/index.ts and actions/* implement domain logic and API calls
- Routes / HTTP Endpoints – (optional) src/routes/* for OAuth or webhooks
- Utility Modules – src/util or src/config or src/db (database connectors, API wrappers, migration scripts)
- Database – local SQLite or managed DB for persistence (optional per app)
- External Services – GitHub, Slack, Linear, Spotify, etc., accessed via util modules
c. Interactions & Data Flow
1. User clicks a widget in the AIOS shell → Browser UI
2. UI invokes Manifest Function (HTTP POST over platform gateway)
3. Manifest function loads AI Module → selects and executes Actions
4. Actions call External Service APIs and/or Database
5. Results bubble back through the Manifest Function → AI Engine → UI renderer
6. UI updates user view / streams messages

##### Architectural Patterns & Design Principles
- Plugin/Serverless architecture: each app is a set of self-contained manifest functions + static UI
- Clear separation: UI (React) vs. Business Logic (AI actions) vs. Persistence/Config vs. External API integration
- Convention over configuration: each app follows identical folder layout, manifest interface, typing (TypeScript)
- Optional microservices: OAuth flows and webhooks live in routes/ as small HTTP handlers

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::external

    %% Antispace AIOS Platform
    subgraph "Antispace AIOS Platform"
        CLI["CLI / Runtime Environment"]:::platform
        Gateway["API Gateway"]:::platform
        AIEngine["Core AI Engine"]:::platform
    end

    %% Generic App Template
    subgraph "Example App Template"
        direction TB
        subgraph "UI Layer (Browser)"
            Page["page.tsx"]:::ui
            Widget["widget.tsx"]:::ui
        end
        subgraph "Manifest Functions"
            ManifestIndex["index.ts"]:::functions
            ManifestFuncs["functions.ts"]:::functions
        end
        subgraph "AI Module & Actions"
            AIModule["index.ts"]:::logic
            Actions["actions/index.ts"]:::logic
        end
        subgraph "Optional Routes"
            RoutesDir["routes/"]:::functions
        end
        subgraph "Utility Modules"
            UtilDir["util/"]:::functions
        end
        DB["Database (optional)"]:::datastore
        Ext["External Services"]:::external
    end

    %% Data Flow
    User -->|"click widget"| Widget
    Widget -->|"HTTP POST"| Gateway
    Gateway -->|"invoke"| ManifestIndex
    ManifestIndex -->|uses| ManifestFuncs
    ManifestFuncs -->|loads| AIModule
    AIModule -->|executes| Actions
    Actions -->|REST API call| Ext
    Actions -->|SQL query| DB
    ManifestIndex -->|"response"| AIEngine
    AIEngine -->|"stream update"| Page
    Page --> User

    %% Platform orchestration
    CLI -->|"discovers apps"| ManifestIndex
    CLI --> AIEngine

    %% Click Events
    click CLI "https://github.com/antispace-ai/aios/blob/main/README.md"
    click docs "https://github.com/antispace-ai/aios/tree/main/docs/"
    click Page "https://github.com/antispace-ai/aios/blob/main/examples/<app-name>/src/ui/page.tsx"
    click Widget "https://github.com/antispace-ai/aios/blob/main/examples/<app-name>/src/ui/widget.tsx"
    click ManifestIndex "https://github.com/antispace-ai/aios/blob/main/examples/<app-name>/src/manifest/index.ts"
    click ManifestFuncs "https://github.com/antispace-ai/aios/blob/main/examples/<app-name>/src/manifest/functions.ts"
    click AIModule "https://github.com/antispace-ai/aios/blob/main/examples/<app-name>/src/ai/index.ts"
    click Actions "https://github.com/antispace-ai/aios/blob/main/examples/<app-name>/src/ai/actions/index.ts"
    click RoutesDir "https://github.com/antispace-ai/aios/tree/main/examples/<app-name>/src/routes/"
    click UtilDir "https://github.com/antispace-ai/aios/tree/main/examples/<app-name>/src/util/"

    %% Styles
    classDef platform fill:#BBDEFB,stroke:#0D47A1
    classDef ui fill:#C8E6C9,stroke:#1B5E20
    classDef functions fill:#FFE0B2,stroke:#E65100
    classDef logic fill:#FFF9C4,stroke:#F57F17
    classDef datastore fill:#EEEEEE,stroke:#424242
    classDef external fill:#E0E0E0,stroke:#757575
```
