# Project Velocity - First Principles_ Multi-Surface Platform and Oracle Expansion

**Date:** 2026-04-16  
**Status:** Active handoff baseline  
**Owner:** Sayan  
**Reviewers:** Sagnik, WebOS owner, backend owner  
**Scope:** iPad residual completion, phone edge apps, Android tablet parity, Oracle schema and template DB expansion, inventory loading pipeline, admin control plane  
**Purpose:** Define the real problem, intended behavior, and architectural logic before implementation extends across multiple product surfaces.

## Executive Summary

Project Velocity currently has a meaningful but uneven product surface:

- WebOS is broad
- iPad has a real native start
- Oracle exists and already has route and schema direction
- inventory assets exist
- backend authority already exists

What is missing is surface completion and normalization.

The next expansion is not "make more screens." The real objective is:

- finish the tablet field product properly
- create narrow edge apps for phone operators
- create durable communication memory so the system can remind operators about prior calls, messages, promises, and follow-up windows
- align all surfaces to one backend and one schema truth
- turn Oracle templates into a governed data product

## Assumptions and Constraints

### Assumptions

- WebOS remains the broad operator shell
- the current iPad Swift app is the native parity reference for tablet work
- Android tablet should mirror the iPad information architecture, not reinvent it
- phone edge apps are lower-density, control-oriented, and communication-aware
- Oracle template generation will be backed by JSON templates and database persistence
- the business requirement includes remembering communication history and follow-up commitments across supported channels

### Constraints

- current repo ownership must be respected
- inventory source files are only partially present and more client data is still pending
- phone call capture and transcription must remain within OS, API, and consent constraints
- WhatsApp, email, and message ingestion must be built around supported business surfaces
- a managed or dedicated work phone does not remove iOS, Android, carrier, or provider restrictions
- backend authority remains in `Project_Velocity/backend/`

## Reference Sources and Rationale

### Local Sources

- `Project_Velocity/README.md`
- `Project_Velocity/app/`
- `Project_Velocity/iOS/velocity/velocity/`
- `Project_Velocity/backend/oracle/router_v1.py`
- `Project_Velocity/backend/oracle/schema_oracle.sql`
- `Project_Velocity/backend/api/routes_oracle.py`
- `Project_Velocity/db assets/Inventory/`

### Upstream or External Sources

- Apple and Android platform rules matter for capture and telephony constraints
- WhatsApp Business Platform capability limits must be respected
- no external framework should override the current Velocity architecture

## Problem Statement

Velocity currently risks product asymmetry:

- WebOS can do more than native surfaces
- iPad exists but is not yet the finished field product
- there is no dedicated phone edge experience for brand reps or realtors
- Oracle template strategy is present but not yet converted into a full template book and DB program
- inventory ingestion is still operator-heavy
- there is no dedicated admin control surface to operate the moving parts coherently

## System Vision

The intended end state is:

- iPad and Android tablet act as fully capable field tablets
- iPhone and Android phone edge apps act as mobile control and communication surfaces
- Oracle becomes the composition and analytical runtime across all surfaces
- templates become governed JSON assets with synthetic expansion capability
- inventory loading becomes an explicit pipeline, not ad hoc manual work
- admin gets a controlled operational surface

## First-Principles Architecture

### Principle 1: Surface specialization is mandatory

Each device class should do the work it is physically good at.

### Principle 2: Backend truth stays centralized

The current FastAPI backend already owns auth, Oracle, CRM direction, and route authority.

### Principle 3: Oracle templates are product assets

Templates must become categorized, versioned, queryable, and persistable.

### Principle 4: Inventory data must become pipelineable

Manual import as the permanent model is not acceptable.

### Principle 5: Mobile capture must be consent-first and platform-realistic

Do not promise unsupported device capture behavior.

### Principle 6: Communication memory is a core product feature

The real requirement is not raw recording for its own sake. The real requirement is durable operator memory:

- what happened with this lead
- what was promised
- when the client said they would return, call back, or decide
- what reminder should fire later

That requirement stays in scope even when some direct OS-level capture paths do not.

## Bottom Line

This work is a multi-surface normalization program around the current Velocity root. The correct implementation path is shared contracts, centralized backend truth, specialized device roles, and a real Oracle template data model.