ORVYCOMPANION · v0.1
ORVY Companion›MVP Architecture
PHASE 0 · WORKING MANUSCRIPT

ORVY Companion — MVP Architecture v0.1

EXPLORATORY DRAFTNOT CANONICALv0.1 · 18 OCT 2026

Human authority, location, tool calls and existing-stack deployment.

Authority statement: This document is a proposal for ORVY Companion; it is not an approved ORVY Core architecture change. Application implementation is not yet authorized.

Document ID: ORVY-COMP-ARCH-001 Status: EXPLORATORY WORKING DRAFT — NOT APPROVED / NOT CANONICAL Prepared: 2026-10-18 Dependency: ORVY-COMP-CHTR-001 Scope: Competition MVP only; no modification to canonical ORVY Core

1. Architecture objectives

Create a useful, secure, cost-bounded, location-aware personal AI companion on infrastructure already available. Preserve separations among identity, consent, context, memory, inference, recommendation, authorized execution, and evidence. Favor a modular ASP.NET Core application over premature distributed systems.

2. Existing-stack baseline

  • Server: Windows Dedicated Server, IIS, HTTPS, Windows service / scheduled worker as appropriate.
  • Application: ASP.NET Core MVC / Web API, C#, server-rendered responsive UI, Bootstrap and TypeScript.
  • Persistence: Microsoft SQL Server in a logically separate ORVY Companion database.
  • AI: OpenAI Responses API with backend-controlled function tools and strict output validation.
  • GIS: Google Maps Platform or another licensed provider, accessed through a replaceable provider adapter.
  • Maps: Mobile-first website with user-initiated current-location requests and manual location fallback.
  • Future mobile: Native wrapper/app evaluated separately if persistent geofencing, background location, or robust push notifications are required.

API credentials are stored server-side, never embedded in published HTML or client JavaScript.

3. Logical component boundaries

Experience

Onboarding, preference management, discovery, conversational interface, map cards, explanations, feedback, and consent settings. No privileged provider secrets in the browser.

Authentication, session security, scoped consent grants, expiry/revocation enforcement, and action approvals. Identity must not be confused with permission. Each location/memory/notification operation checks a specific current grant.

Location context

Receives user-initiated device coordinates or a manually chosen area. Applies precision minimization, throttling, and expiry. Exact coordinates remain ephemeral by default; longer retention requires a separate user-visible feature and consent.

Places integration

Normalizes place records, provenance, provider attribution, fields, freshness, and routing metadata from licensed APIs. Cached provider content follows provider-specific terms; do not assume indefinite copying/storage is permitted.

Agent orchestrator

Transforms an authorized user or discovery request into controlled model/tool turns. Tool execution happens in the backend. The model cannot directly approve external actions, widen scopes, or bypass deterministic safety checks.

Opportunity and recommendation engine

Filters candidate places deterministically for known user interests, distance, timeliness, duplication, availability evidence, quiet hours, and frequency caps. Model-generated prose explains the recommendation but does not override eligibility rules.

Memory and feedback

Stores user-supplied preferences separately from inferred preferences and ephemeral observations. Inferences carry provenance, confidence, retention period, user visibility, and deletion/rejection controls. Memory access does not imply authority for action.

Notifications

Begins with in-app recommendations and explicitly opted-in browser notifications where supported. Scheduled and geofence delivery are capability-gated; do not promise reliable closed-app foreground/background tracking through the browser.

Evidence and audit

Records tool call purpose, consent-grant reference, provider provenance, outcome, feedback, safety interventions, and error states without logging unnecessary raw health text or precise coordinates.

4. Initial server modules

  • Companion.Identity
  • Companion.Consent
  • Companion.Profile
  • Companion.Context
  • Companion.Places
  • Companion.Agent
  • Companion.Recommendations
  • Companion.Notifications
  • Companion.Audit

These are logical boundaries; physical project count is deferred. A compact modular monolith is acceptable for the MVP.

5. Suggested first-pass data concepts

  • UserProfile: stable user key, locale, user-controlled profile defaults.
  • UserInterest: explicit or inferred origin, confidence, consent provenance, edit/delete status.
  • ConsentGrant: subject, scope, grant time, expiry, revocation, policy/version.
  • ContextObservation: minimal event type, source, validity window, no indefinite exact location by default.
  • MemoryEntry: source, sensitivity, purpose, confidence, expiry, visibility, deletion marker.
  • Recommendation: candidate, evidence/source, rationale, dispatch/expiration state.
  • RecommendationFeedback: accepted, dismissed, blocked topic, not interested.
  • ToolExecution: model request, tool identifier, sanitized parameters, outcome and provenance.
  • ActionApproval: action proposal, human approval and execution result if supported later.
  • AuditEvent: append-only consent/privileged operation evidence.

All person-linked data uses access controls and a defined retention/deletion policy; detailed schema, encryption/key design, and migration policy are G1 decisions.

6. Initial function tool contracts

  • get_user_context(purpose, allowed_scopes) returns only authorized preferences and relevant non-sensitive memory.
  • find_nearby_places(category, coordinates_or_area, radius, limit) returns attributed provider candidates; enforce maximum radius and quota.
  • get_place_details(provider_place_id, fields) retrieves attributed, current place facts.
  • get_route_options(origin, destination, mode) returns provider-reported travel estimates; never infer nonexistent route metrics.
  • find_verified_events(place_id, date_window) returns events only when authoritative verified sources are configured; otherwise returns unavailable.
  • propose_memory_update(kind, value, provenance) creates a proposal, not a silent write.
  • generate_recommendation(candidates, context) returns constrained structured output with evidence references.

Tools are proposals. Back-end validation, policy enforcement, and source-of-truth APIs determine what executes.

7. Normal proactive request flow

  1. A permitted user action or explicitly opted-in discovery trigger occurs.
  2. The application checks active consent, location freshness, and frequency limits.
  3. The Places adapter retrieves bounded nearby candidates.
  4. Deterministic relevance filters remove unusable, repeated, or unsupported candidates.
  5. The agent may request approved details or relevant non-sensitive memory.
  6. Structured output validation confirms sources, claims, safety, and language.
  7. Recommendation dispatch checks quiet hours and current consent again.
  8. The user can open directions, dismiss, suppress, or adjust preferences.
  9. Minimal action and provenance records are kept for evaluation/auditing.

8. Health and financial boundaries

Health: user-initiated general information and locating nearby services may be supported. No unsupervised diagnosis, prescribing, dose invention, or urgent-care delays. Red-flag escalation must be designed and tested. Sensitive health narratives are not auto-saved as behavioral memory.

Finance: early MVP may locate nearby banks or ATMs from licensed places information. No account integrations, personalized financial product endorsements, balance interpretation, or payment execution.

9. Security and privacy requirements

Use HTTPS, server-side API tokens, role/subject authorization, CSRF protection for MVC write actions, rate limiting, input/output validation, safe tool allowlists, secure session cookies, logging redaction, and encrypted backup controls. Treat external place descriptions and pages as untrusted data, never as instructions to the AI agent. Prompt injection tests are mandatory before pilot.

Provide user-visible controls for memory review, preference correction, location pausing, notification limits, and deletion requests. Provider-specific consent and international privacy requirements require separate review before public launch.

10. Hosting and release topology

Development: local Visual Studio and SQL environment. Staging: isolated IIS site/application pool and separate Companion staging database; mock/simulated-location mode clearly labeled for tests. Production: isolated IIS application pool, HTTPS hostname, SQL least-privilege credentials, worker service, backup/restore plan, alerting, and consumption limits.

Do not reuse MHERC tables, connection strings, credentials, or billing ledgers. Shared physical Windows/SQL resources are allowed; isolation is mandatory.

11. Operational budgets and safeguards

Set external API request quotas and budget alerts; debounce GPS sampling; only ask the model after cheap filtering; cap tool loops and responses; implement idempotent recommendation dispatch; use timeouts/circuit breakers; test degraded behavior when AI, Places, or routing services fail.

12. Evaluation and readiness

Create deterministic seeded test fixtures, synthetic Dubai and Philippine location scenarios, explicit evidence freshness cases, consent-revocation tests, health escalation cases, hallucination tests, and device compatibility checks. Record latency and cost per successful recommendation.

13. Future ORVY alignment

The prototype may inform a proposed ORVY Amplifier contract. It must not substitute itself for ORVY Core, Synapse, Reflex, or their admission/governance machinery. Promotion of findings into canonical ORVY architecture requires a separate explicit process.

Current gate: G1, OPEN. All service boundaries and implementation choices remain reviewable.

Human-readable derivative of companion/source/ORVY-COMP-ARCHITECTURE-v0.1.md. Source Markdown governs this draft; explicit review is required for promotion.

OverviewProduct CharterMVP ArchitectureDelivery Roadmap