OpportunityOS

What it is

OpportunityOS is a private-first business-development operating system for a small software studio. It brings opportunity signals, lead context, outreach preparation, and pipeline follow-up into one owner-controlled workspace.

The problem and business value

Business-development signals often arrive through disconnected sources, while follow-up decisions are difficult to explain or audit. OpportunityOS makes the path from signal to opportunity visible: source provenance is retained, scoring and duplicate suggestions are reviewable, outreach is prepared from approved context, and next actions can be tracked against the pipeline.

The product is designed to improve decision quality and follow-through. It does not claim customer adoption, revenue, conversion, or other commercial outcomes that are not measured in this repository.

What it does today

• Authenticated operators can manage owner-scoped companies, contacts, opportunities, pipeline events, proposals, meeting follow-ups, and analytics.
• CSV and adapter-based sources can be normalized into a shared ingestion model with source labels, dataset context, provenance, and malformed-record isolation.
• Duplicate matches are suggestions rather than automatic merges. Operators can review, keep, mark duplicate, or record a merge decision with a note.
• Consented external leads can be promoted through an explicit company/contact/opportunity flow while preserving source links and idempotent promotion behavior.
• The protected Integrations Hub brings provider status, credential rotation, explicit health tests, and lead management together without returning stored keys to the browser.
• The anonymous landing page is intentionally separate from the workspace and shows only deterministic, labelled synthetic demo data.

Integrations and data flow

OpportunityOS uses server-side boundaries so provider work can be replaced or disabled without moving credentials into the client.

• Local Business is an asynchronous server-to-server bridge. The separate service performs discovery; OpportunityOS stores owner-scoped search history, job state, normalized lead snapshots, public contact observations, and provenance. The bridge and protected operator surface are implemented, while recovery/reconciliation and hosted-service verification remain pending. The feature is disabled by default and has a deterministic mock-provider path for testing.
• Apollo batches enter through a versioned, owner-bound receiver that records idempotency and job/batch/page lineage, isolates malformed records, and maps accepted records to pending source candidates. The receiver does not write directly to CRM or outreach, does not retain raw Apollo payloads, and remains disabled until the scraper contract, authentication, owner binding, retention, and compliance decisions are completed.
• Apollo and Hunter support protected API-key setup and explicit account/health checks. Keys are encrypted server-side and shown only as connection metadata. Apollo partner OAuth is not represented as a generic Google login; that flow requires provider approval.
• Google Drive has a least-privilege OAuth and encrypted-token connector foundation with lineage and revocation controls. A storage-aware import, editing, export, and remote-conflict workflow is planned rather than silently assumed.

AI or automation workflow

Deterministic templates are the default draft generator. An OpenAI-backed generator is available as an opt-in, schema-validated provider boundary, but external AI is disabled by default. When used, it assists with editable drafts and does not make the workflow autonomous.

Scheduled ingestion supports source locks, bounded retries, timeouts, cursors, and explicit succeeded, partial, failed, or skipped states. These controls make recurring work observable; they do not replace operator review.

This product does not present an automatic AI chat assistant. Its AI capability is draft assistance, separate from delivery.

Lead, email, notification, or collaboration flow

An imported lead remains in source-aware review until an operator chooses what to do with it. CRM promotion is owner-scoped, checks consent where required, preserves provenance, and avoids duplicate company or contact creation.

Outreach drafts are editable and approval-first. A delivery-capable message requires an email channel, subject, contact address, and a documented consented or legitimate_interest basis. Duplicate recipient threads are suppressed. draft_only is the default; send_after_approval is an explicit operator choice with database gates, idempotency, and audit events. Resend and Gmail boundaries exist for controlled delivery and drafts, but external sending remains disabled until the relevant provider and release settings are approved.

Security/privacy boundaries

The dashboard requires an authenticated session, and application data is owner-scoped through Supabase row-level security. Provider keys and OAuth tokens stay server-side; connector secrets are encrypted before persistence, and OAuth callbacks use protected state. Request limits, security headers, webhook verification, and audit records provide additional safeguards.

The public landing page does not read CRM, connector, scraper, analytics, or customer data. Its metrics are deterministic synthetic fixtures. Product-health analytics is kept separate from CRM analytics and must not receive names, contact details, message bodies, identifiers, provider payloads, or pipeline values. Promoted CRM leads are protected from accidental deletion through a source list; a fuller export/delete workflow is still an operational follow-up.

What is coming next

The immediate work is to complete local database and authenticated browser evidence, close the Local Business recovery path, and finish the Apollo scraper contract and enablement review. Hosted use also requires provider terms and lawful-basis review, retention/deletion decisions, backup and restore evidence, hosted Auth protections, distributed rate limiting, and security/performance checks.

Further product direction includes a storage-aware Google Drive workflow with explicit import/export and revision conflict handling, provider-approved Apollo account handoff, and connector identity suitable for a broader multi-user model.

Current activity or evidence from the project

As of 2026-08-26, the current main branch includes the Integrations Hub, Apollo ingress boundary, and owner-scoped lead controls. The repository records passing application checks, a production build and performance check, 644 automated tests, and coverage above the configured thresholds. Six Chromium boundary journeys pass independently of the local database. Full authenticated end-to-end, pgTAP, and generated-type verification remain pending because the local Supabase runtime is not currently available for this project.

These are repository verification signals, not claims about users, revenue, delivery volume, or production adoption.