# Oracle Schema and Root API Spec_ Multi-Surface Platform

**Date:** 2026-04-16  
**Status:** Schema extension direction  
**Owner:** Sayan  
**Reviewers:** backend and schema reviewers  
**Purpose:** Define how the current Oracle and root API shape should be extended for this workstream.

## 1. Current Truth

Existing Oracle schema already includes:

- canvas pages
- revisions
- components
- prompt executions
- component templates
- forks
- merge requests
- lineage
- audit

Reference:

- `Project_Velocity/backend/oracle/schema_oracle.sql`

## 2. Required Extensions

Recommended additions:

- `oracle_template_chapters`
- `oracle_template_subchapters`
- `oracle_template_seed_examples`
- `oracle_synthetic_generation_jobs`
- `inventory_properties`
- `inventory_import_batches`
- `inventory_media_assets`
- `edge_communication_events`
- `edge_communication_memory_facts`
- `edge_transcription_jobs`
- `edge_transcript_segments`
- `user_calendar_events`
- `insight_recommendations`
- `admin_action_events`

## 3. Root API Additions

Recommended route families:

- `GET /oracle/template-chapters`
- `GET /oracle/template-subchapters`
- `GET /oracle/component-templates`
- `POST /oracle/component-templates/seed`
- `POST /oracle/component-templates/synthetic-jobs`
- `POST /inventory/import-batches`
- `PATCH /inventory/properties/{propertyId}`
- `GET /mobile-edge/events`
- `GET /mobile-edge/memory`
- `POST /mobile-edge/imports`
- `POST /mobile-edge/notes`
- `GET /mobile-edge/calendar`
- `POST /mobile-edge/calendar`
- `PATCH /mobile-edge/calendar/{calendarEventId}`
- `GET /mobile-edge/transcripts/{eventId}`
- `GET /mobile-edge/insights/{leadId}`
- `GET /admin-surface/health`
- `POST /admin-surface/actions`

## 4. Schema Rules

- do not replace current Oracle tables
- extend cleanly
- keep lifecycle and audit fields
- keep provider provenance for communication records
- keep role and tenancy fields where current Oracle patterns already use them