Files

sayan 84e439712c feat/#24 WebOS Completion (#25 )

#24 WebOS Completion

Co-authored-by: Sayan Datta <sayan@Sayans-MacBook-Air.local>
Reviewed-on: sagnik/Project_Velocity#25

2026-04-18 18:59:04 +05:30

5.0 KiB

Raw Blame History

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.

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.

5.0 KiB Raw Blame History