# ajay-1011-git/ramwise architecture

> Architecture diagram of the GitHub repository ajay-1011-git/ramwise, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ajay-1011-git/ramwise
- Repository: https://github.com/ajay-1011-git/ramwise

## Overview

RAMWise collects Android usage and device telemetry, predicts likely next apps, and uses the prediction plus device state to recommend cache placement. The dashboard presents predictions, allocation decisions, live metrics, and LRU comparisons. The README documents the Transformer/PPO pipeline and three-tier cache; sampled code confirms the API, telemetry persistence, model inference, dashboard requests, and cache behavior. Benchmark and training links reflect documented capabilities, though their full runtime wiring was not sampled.

Main entry points: [`backend/api/main.py`](https://github.com/ajay-1011-git/ramwise/blob/main/backend/api/main.py) (FastAPI endpoints), [`backend/benchmarking/benchmark.py`](https://github.com/ajay-1011-git/ramwise/blob/main/backend/benchmarking/benchmark.py) (Benchmark engine), [`backend/cache_simulator/cache.py`](https://github.com/ajay-1011-git/ramwise/blob/main/backend/cache_simulator/cache.py) (Adaptive cache), [`backend/rl_allocator/train_rl.py`](https://github.com/ajay-1011-git/ramwise/blob/main/backend/rl_allocator/train_rl.py) (PPO training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client surfaces"]
  node_android["Android monitor"]
  node_dashboard["React dashboard<br/>[App.tsx]"]
  node_dashboard_api["Dashboard API client<br/>[api.ts]"]
end

subgraph group_service["Prediction service"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_database_helpers["SQLite access<br/>[database.py]"]
  node_telemetry_db[("Telemetry database<br/>[database.py]")]
  node_transformer["App Transformer<br/>[model.py]"]
  node_transformer_weights["Transformer weights"]
end

subgraph group_allocation["Cache allocation"]
  node_ppo_agent["PPO inference<br/>[main.py]"]
  node_ppo_weights["PPO model weights"]
  node_adaptive_cache["Adaptive cache<br/>[cache.py]"]
  node_lru_cache["LRU baseline<br/>[cache.py]"]
end

subgraph group_learning["Model learning"]
  node_memory_env["Memory environment<br/>[memory_env.py]"]
  node_rl_training["PPO training<br/>[train_rl.py]"]
end

subgraph group_insights["Metrics and benchmarks"]
  node_benchmark_engine["Benchmark engine<br/>[benchmark.py]"]
  node_benchmark_data["Benchmark results"]
end

node_user(("Device user"))
node_http_service{{"RAMWise HTTP API"}}

node_user -->|"uses"| node_android
node_android -->|"posts telemetry"| node_http_service
node_http_service -->|"routes requests"| node_api
node_dashboard -->|"requests data"| node_dashboard_api
node_dashboard_api -->|"calls endpoints"| node_http_service
node_api -->|"queries and writes"| node_database_helpers
node_database_helpers -->|"reads and writes"| node_telemetry_db
node_api -->|"predicts apps"| node_transformer
node_transformer -.->|"loads weights"| node_transformer_weights
node_api -->|"selects allocation"| node_ppo_agent
node_ppo_agent -.->|"loads policy"| node_ppo_weights
node_api -.->|"uses cache behavior"| node_adaptive_cache
node_benchmark_engine -->|"benchmarks"| node_adaptive_cache
node_benchmark_engine -->|"compares baseline"| node_lru_cache
node_api -.->|"reads results"| node_benchmark_data
node_benchmark_engine -.->|"produces results"| node_benchmark_data
node_rl_training -->|"trains against"| node_memory_env
node_memory_env -.->|"models tier policy"| node_adaptive_cache
node_rl_training -->|"saves policy"| node_ppo_weights

click node_android "https://github.com/ajay-1011-git/ramwise/blob/main/android-client/app/src/main/java/com/ramwise/telemetry/TelemetryService.kt"
click node_dashboard "https://github.com/ajay-1011-git/ramwise/blob/main/dashboard/src/App.tsx"
click node_dashboard_api "https://github.com/ajay-1011-git/ramwise/blob/main/dashboard/src/api.ts"
click node_api "https://github.com/ajay-1011-git/ramwise/blob/main/backend/api/main.py"
click node_database_helpers "https://github.com/ajay-1011-git/ramwise/blob/main/backend/api/database.py"
click node_telemetry_db "https://github.com/ajay-1011-git/ramwise/blob/main/backend/api/database.py"
click node_transformer "https://github.com/ajay-1011-git/ramwise/blob/main/backend/transformer/model.py"
click node_transformer_weights "https://github.com/ajay-1011-git/ramwise/tree/main/models/transformer_weights"
click node_ppo_agent "https://github.com/ajay-1011-git/ramwise/blob/main/backend/api/main.py"
click node_ppo_weights "https://github.com/ajay-1011-git/ramwise/tree/main/models/rl_models"
click node_adaptive_cache "https://github.com/ajay-1011-git/ramwise/blob/main/backend/cache_simulator/cache.py"
click node_lru_cache "https://github.com/ajay-1011-git/ramwise/blob/main/backend/cache_simulator/cache.py"
click node_memory_env "https://github.com/ajay-1011-git/ramwise/blob/main/backend/rl_allocator/memory_env.py"
click node_rl_training "https://github.com/ajay-1011-git/ramwise/blob/main/backend/rl_allocator/train_rl.py"
click node_benchmark_engine "https://github.com/ajay-1011-git/ramwise/blob/main/backend/benchmarking/benchmark.py"
click node_benchmark_data "https://github.com/ajay-1011-git/ramwise/blob/main/datasets/ubiqlog/benchmark_report.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_android,node_dashboard,node_dashboard_api,node_user toneBlue
class node_api,node_database_helpers,node_telemetry_db,node_transformer,node_transformer_weights toneAmber
class node_ppo_agent,node_ppo_weights,node_adaptive_cache,node_lru_cache,node_http_service toneMint
class node_memory_env,node_rl_training toneRose
class node_benchmark_engine,node_benchmark_data toneIndigo
```

## Components

### Client surfaces

- [Android monitor](https://github.com/ajay-1011-git/ramwise/blob/main/android-client/app/src/main/java/com/ramwise/telemetry/TelemetryService.kt): `android-client/app/src/main/java/com/ramwise/telemetry/TelemetryService.kt`
- [React dashboard](https://github.com/ajay-1011-git/ramwise/blob/main/dashboard/src/App.tsx): `dashboard/src/App.tsx`
- [Dashboard API client](https://github.com/ajay-1011-git/ramwise/blob/main/dashboard/src/api.ts): `dashboard/src/api.ts`

### Prediction service

- [FastAPI endpoints](https://github.com/ajay-1011-git/ramwise/blob/main/backend/api/main.py): `backend/api/main.py`
- [SQLite access](https://github.com/ajay-1011-git/ramwise/blob/main/backend/api/database.py): `backend/api/database.py`
- [Telemetry database](https://github.com/ajay-1011-git/ramwise/blob/main/backend/api/database.py): `backend/api/database.py`
- [App Transformer](https://github.com/ajay-1011-git/ramwise/blob/main/backend/transformer/model.py): `backend/transformer/model.py`
- [Transformer weights](https://github.com/ajay-1011-git/ramwise/tree/main/models/transformer_weights): `models/transformer_weights`

### Cache allocation

- [PPO inference](https://github.com/ajay-1011-git/ramwise/blob/main/backend/api/main.py): `backend/api/main.py`
- [PPO model weights](https://github.com/ajay-1011-git/ramwise/tree/main/models/rl_models): `models/rl_models`
- [Adaptive cache](https://github.com/ajay-1011-git/ramwise/blob/main/backend/cache_simulator/cache.py): `backend/cache_simulator/cache.py`
- [LRU baseline](https://github.com/ajay-1011-git/ramwise/blob/main/backend/cache_simulator/cache.py): `backend/cache_simulator/cache.py`

### Model learning

- [Memory environment](https://github.com/ajay-1011-git/ramwise/blob/main/backend/rl_allocator/memory_env.py): `backend/rl_allocator/memory_env.py`
- [PPO training](https://github.com/ajay-1011-git/ramwise/blob/main/backend/rl_allocator/train_rl.py): `backend/rl_allocator/train_rl.py`

### Metrics and benchmarks

- [Benchmark engine](https://github.com/ajay-1011-git/ramwise/blob/main/backend/benchmarking/benchmark.py): `backend/benchmarking/benchmark.py`
- [Benchmark results](https://github.com/ajay-1011-git/ramwise/blob/main/datasets/ubiqlog/benchmark_report.json): `datasets/ubiqlog/benchmark_report.json`

### Other components

- **Device user**
- **RAMWise HTTP API**

## Connections

- Device user → Android monitor: uses
- Android monitor → RAMWise HTTP API: posts telemetry
- RAMWise HTTP API → FastAPI endpoints: routes requests
- React dashboard → Dashboard API client: requests data
- Dashboard API client → RAMWise HTTP API: calls endpoints
- FastAPI endpoints → SQLite access: queries and writes
- SQLite access → Telemetry database: reads and writes
- FastAPI endpoints → App Transformer: predicts apps
- App Transformer → Transformer weights: loads weights
- FastAPI endpoints → PPO inference: selects allocation
- PPO inference → PPO model weights: loads policy
- FastAPI endpoints → Adaptive cache: uses cache behavior
- Benchmark engine → Adaptive cache: benchmarks
- Benchmark engine → LRU baseline: compares baseline
- FastAPI endpoints → Benchmark results: reads results
- Benchmark engine → Benchmark results: produces results
- PPO training → Memory environment: trains against
- Memory environment → Adaptive cache: models tier policy
- PPO training → PPO model weights: saves policy