ZARVIS Mobile

ZARVIS is a personal AI digital assistant and agent platform for Web + Android.

It is designed around one shared ZARVIS Brain that powers conversations, agents, memory, projects, tasks, tools, policy, permissions and verification across platforms.

Product vision

ZARVIS should feel like one intelligent personal agent available everywhere:

Understand → Plan → Ask for required access → Execute real work → Verify → Explain → Remember only when appropriate

The product is not just a chatbot or dashboard. It is being built as a real agent platform with truthful capabilities and user-controlled permissions.

---

🧠 One ZARVIS Brain

Web and Android are first-class clients of the same core system.

                       ZARVIS BRAIN
                            │
              ┌─────────────┴─────────────┐
              │                           │
          WEB CLIENT                 ANDROID CLIENT
              │                           │
              └─────────────┬─────────────┘
                            │
                    Shared Agent Platform
                            │
          ┌─────────────────┼─────────────────┐
          │                 │                 │
        Memory            Agents            Tasks
          │                 │                 │
          └──────────── ToolPipeline ─────────┘
                            │
                     Policy + Security
                            │
                        Verification

The clients do not maintain separate AI brains.

Web

The Web version is a full AI workspace for:

• Chat
• Work / Projects
• Agents
• Tasks
• Files
• Research
• Creative
• Business
• Developer workflows
• Activity
• Plans & Usage
• Settings

The responsive Web application should work across desktop, tablet and mobile browsers.

Web Chat and navigation

Everything below is a real client-side behaviour (web/chat-kit.js; the pure rules are unit tested in web/logic.js):

• Chat history. A side panel (and the sidebar, Home and Activity) lists your chats, newest first. The browser keeps an index of ids, titles and times in localStorage and tops it up from GET /api/v1/conversations (metadata only, the account's own chats), so history follows the account to another device or a cleared browser; if that request fails the list simply stays as it is. Opening a chat loads its real messages from the server. A chat you remove from the list stays hidden on that browser until you write in it again; the index and the hidden ids are cleared on sign-out.
• Composer. A / command menu (prompts to edit, or real actions), drafts that survive a reload, drag-and-drop and paste of files and images.
• Messages. Day dividers, Copy / Edit on your own messages, one-tap refine follow-ups under the newest reply, and export of a chat as Markdown or text. Replies render headings, lists, tables (scrolling inside their own frame), block quotes and syntax-coloured code for common languages; everything is escaped first.
• Pages. Home, Chat, Work (Projects, Files, Research, Tasks, Outputs), Agents, Activity, Plans & Usage and Settings, plus Developer Agent and Usage & Metrics when Developer access is on. Work keeps everything that belongs to a goal together and is stored on the server with the account; Tasks (#/work/tasks, g then t, as a list or a board) records real task status and runs a step only when you press Run; Home shows a "Your workspace" dashboard below its first screen; Activity is one merged feed of what really happened. The phone tab bar is Home, Work, Chat, Agents, Settings, and the menu drawer has everything else. WORKSPACE.md describes the pages, the data and API they use, and what they do not do; DESIGN_SYSTEM.md describes the tokens and components.
• Navigation. Breadcrumbs, #/chat/<id> links, remembered scroll position on Back, a collapsible sidebar, a skip link, scroll-to-top, and keyboard shortcuts (? lists them).

Android

The Android version is the personal device agent.

It can progressively support authorized capabilities such as:

• Microphone and voice
• Contacts
• Phone/calling
• Notifications
• Camera
• Photos
• Files/document picker
• Location
• Calendar
• Alarms
• Bluetooth/nearby devices
• Supported Android system actions

Android permissions are controlled by Android. ZARVIS explains why access is needed, handles user decisions and verifies the real permission/tool result.

---

Core product rules

1. No fake capabilities.
2. No fake execution.
3. No fake verification.
4. No fake progress or activity.
5. No silent permission escalation.
6. Least privilege by default.
7. Permission and action confirmation are separate.
8. Every capability has a truthful status.
9. UI and voice states must reflect actual backend/tool state.
10. Sensitive actions require appropriate confirmation.
11. Android security cannot be bypassed.
12. Web and Android must use the shared Brain and common policy/tool architecture.

Capability states:

• WORKING — implemented, connected, tested and verified
• PARTIAL — some real functionality exists
• PLANNED — designed but not active
• UNSUPPORTED — no legitimate current route

---

Agent architecture

The common execution path is:

User
 ↓
Natural Language / Voice / File
 ↓
Intent
 ↓
ZARVIS Brain
 ↓
Plan
 ↓
Agent / Skill
 ↓
Capability Check
 ↓
Permission / Integration Check
 ↓
Risk Check
 ↓
Confirmation when required
 ↓
ToolPipeline
 ↓
Web API / Android API / Local Tool
 ↓
Verification
 ↓
Task / Activity State
 ↓
Response
 ↓
Voice / UI
 ↓
Memory when appropriate

The LLM proposes actions. Policy and tool layers decide whether they are allowed and executable. Platform security controls platform permissions. Verification determines what actually happened.

---

A→Z implementation order

The permanent implementation order is:

1. Android Mobile Access + Permission Intelligence
2. Personal AI Core + Memory
3. Voice AI
4. Research
5. Study
6. Documents
7. Writing / Communication
8. Creative
9. Life Organizer
10. Real Task / Automation Engine
11. Phone / Device Agent
12. Notification Intelligence
13. Business Agent
14. Finance Assistant
15. Shopping Agent
16. Travel Agent
17. Universal Translation
18. Email / Communication Agent
19. Meeting Agent
20. Developer Agent
21. Skills + Multi-Agent
22. Personal Dashboard
23. Privacy + Security Center
24. Family Workspace
25. Integrations Hub
26. Smart Home / IoT

Phase 1 is the current engineering gate. Later phases must not bypass or weaken its permission, policy and verification architecture.

---

Cross-device continuity

ZARVIS should allow real stored work to continue between platforms.

Example:

Web: “Research this project.”

Later:

Android: “जहाँ छोड़ा था वहीं से continue करो।”

The system may recover only state that was actually stored, such as:

• project
• conversation
• plan
• completed/pending steps
• files
• research
• decisions
• confirmations
• connected tools
• task state

No fake memory or fake continuity.

---

Privacy and security

The architecture follows:

• least privilege
• data minimization
• account isolation
• ownership checks
• safe logging
• encrypted secrets
• integration revocation
• permission revocation handling
• user-controlled memory
• per-user authorization where required

Permission does not equal unlimited future authorization.

For example:

• Contacts access ≠ permission to share contacts
• Notification access ≠ permission to read everything aloud
• Phone access ≠ permission to call arbitrary targets
• File access ≠ permission to upload everything
• Accessibility ≠ universal automation

---

Root documentation

All permanent Markdown documentation is kept in the repository root so the project is easy to understand directly from GitHub.

File	Purpose
ZARVIS_MASTER_PRODUCT_BLUEPRINT.md	Authoritative A→Z product, UX, architecture and execution blueprint
MASTER_SPEC.md	Master-spec navigation/compatibility entry point
UI_UX_DEEP_SCAN.md	Web UI/UX deep scan: page list, content placement, layout rules, link map, open decisions
ARCHITECTURE.md	System and shared Brain architecture
SECURITY.md	Security, risk and authorization rules
PRIVACY.md	Privacy and notification privacy rules
AI_ARCHITECTURE.md	AI, planning, agents and execution boundary
AI_MODEL_GATEWAY.md	AI Model Gateway: providers (Gemini, OpenRouter), capability routing, fallback, configuration, Vercel setup, troubleshooting
SKILLS.md	Skill model and capability contracts
DEVELOPER_AGENT.md

Documentation rule: ZARVIS_MASTER_PRODUCT_BLUEPRINT.md remains the single authoritative source of truth. Supporting root-level MD files must not contradict it.

---

Development rule

Before changing code:

1. Read ZARVIS_MASTER_PRODUCT_BLUEPRINT.md.
2. Identify the current implementation phase.
3. Inspect existing Web and Android architecture.
4. Preserve working functionality.
5. Search for duplicate implementations.
6. Use the shared Brain, policy and ToolPipeline.
7. Keep platform-specific adapters isolated.
8. Add tests for important behavior.
9. Never mark a capability WORKING without evidence.
10. Verify Web, Android and cross-device behavior when relevant.

Current milestone

PHASE 1 — Android Mobile Access + Permission Intelligence

The goal is to establish the secure, permission-aware foundation before activating later agent capabilities.

---

ZARVIS — One Brain. Web + Android. Real Agent. Real Execution. Real Verification.