mirror of
https://github.com/kennethnym/aris.git
synced 2026-02-02 13:11:17 +00:00
111 lines
5.6 KiB
Markdown
111 lines
5.6 KiB
Markdown
|
# ARIS Architecture Draft
|
||
|
|
|
||
|
|
> This is a working draft from initial architecture discussions. Not final documentation.
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
ARIS is an AI-powered personal assistant. The core aggregates data from various sources and compiles a feed of contextually relevant items - similar to Google Now. The feed shows users useful information based on their current context (date, time, location).
|
||
|
|
|
||
|
|
Examples of feed items:
|
||
|
|
|
||
|
|
- Upcoming calendar events
|
||
|
|
- Nearby locations
|
||
|
|
- Current weather
|
||
|
|
- Alerts
|
||
|
|
|
||
|
|
## Design Principles
|
||
|
|
|
||
|
|
1. **Extensibility**: The core must support different data sources, including third-party sources.
|
||
|
|
2. **Separation of concerns**: Core handles data only. UI rendering is a separate system.
|
||
|
|
3. **Parallel execution**: Sources run in parallel; no inter-source dependencies.
|
||
|
|
4. **Graceful degradation**: Failed sources are skipped; partial results are returned.
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────────────────────────────────────────────────┐
|
||
|
|
│ Backend │
|
||
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
|
||
|
|
│ │ aris-core │ │ Sources │ │ UI Registry │ │
|
||
|
|
│ │ │ │ (plugins) │ │ (schemas from │ │
|
||
|
|
│ │ - Reconciler│◄───│ - Calendar │ │ third parties)│ │
|
||
|
|
│ │ - Context │ │ - Weather │ │ │ │
|
||
|
|
│ │ - FeedItem │ │ - Spotify │ │ │ │
|
||
|
|
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
|
||
|
|
│ │ │ │
|
||
|
|
│ ▼ ▼ │
|
||
|
|
│ Feed (data only) UI Schemas (JSON) │
|
||
|
|
└─────────────────────────────────────────────────────────────┘
|
||
|
|
│ │
|
||
|
|
▼ ▼
|
||
|
|
┌─────────────────────────────────────────────────────────────┐
|
||
|
|
│ Frontend │
|
||
|
|
│ ┌──────────────────────────────────────────────────────┐ │
|
||
|
|
│ │ Renderer │ │
|
||
|
|
│ │ - Receives feed items │ │
|
||
|
|
│ │ - Fetches UI schema by item type │ │
|
||
|
|
│ │ - Renders using json-render or similar │ │
|
||
|
|
│ └──────────────────────────────────────────────────────┘ │
|
||
|
|
└─────────────────────────────────────────────────────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
## Core Package (`aris-core`)
|
||
|
|
|
||
|
|
The core is responsible for:
|
||
|
|
|
||
|
|
- Defining the context and feed item interfaces
|
||
|
|
- Providing a reconciler that orchestrates data sources
|
||
|
|
- Returning a flat list of prioritized feed items
|
||
|
|
|
||
|
|
### Key Concepts
|
||
|
|
|
||
|
|
- **Context**: Time and location (with accuracy) passed to all sources
|
||
|
|
- **FeedItem**: Has an ID (source-generated, stable), type, priority, timestamp, and JSON-serializable data
|
||
|
|
- **DataSource**: Interface that third parties implement to provide feed items
|
||
|
|
- **Reconciler**: Orchestrates sources, runs them in parallel, returns items and any errors
|
||
|
|
|
||
|
|
## Data Sources
|
||
|
|
|
||
|
|
Key decisions:
|
||
|
|
|
||
|
|
- Sources receive the full context and decide internally what to use
|
||
|
|
- Each source returns a single item type (e.g., separate "Calendar Source" and "Location Suggestion Source" rather than a combined "Google Source")
|
||
|
|
- Sources live in separate packages, not in the core
|
||
|
|
- Sources are responsible for:
|
||
|
|
- Transforming their domain data into feed items
|
||
|
|
- Assigning priority based on domain logic (e.g., "event starting in 10 minutes" = high priority)
|
||
|
|
- Returning empty arrays when nothing is relevant
|
||
|
|
|
||
|
|
### Configuration
|
||
|
|
|
||
|
|
Configuration is passed at source registration time, not per reconcile call. Sources can use config for filtering/limiting (e.g., "max 3 calendar events").
|
||
|
|
|
||
|
|
## Feed Output
|
||
|
|
|
||
|
|
- Flat list of `FeedItem` objects
|
||
|
|
- No UI information (no icons, card types, etc.)
|
||
|
|
- Items are a discriminated union by `type` field
|
||
|
|
- Reconciler sorts by priority; can act as tiebreaker
|
||
|
|
|
||
|
|
## UI Rendering (Separate from Core)
|
||
|
|
|
||
|
|
The core does not handle UI. For extensible third-party UI:
|
||
|
|
|
||
|
|
1. Third-party apps register their UI schemas through the backend (UI Registry)
|
||
|
|
2. Frontend fetches UI schemas from the backend
|
||
|
|
3. Frontend matches feed items to schemas by `type` and renders accordingly
|
||
|
|
|
||
|
|
This approach:
|
||
|
|
|
||
|
|
- Keeps the core focused on data
|
||
|
|
- Works across platforms (web, React Native)
|
||
|
|
- Avoids the need for third parties to inject code into the app
|
||
|
|
- Uses a json-render style approach for declarative UI from JSON schemas
|
||
|
|
|
||
|
|
Reference: https://github.com/vercel-labs/json-render
|
||
|
|
|
||
|
|
## Open Questions
|
||
|
|
|
||
|
|
- Exact schema format for UI registry
|
||
|
|
- How third parties authenticate/register their sources and UI schemas
|