126 lines
5.0 KiB
Markdown
126 lines
5.0 KiB
Markdown
# 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.
|