IntentGraph

Evidence-backed buyer-intent research that keeps every conclusion attached to its source.

IntentGraph turns seller material and public market signals into reviewed, explainable opportunities. It combines immutable document evidence, monitored sources, company resolution, time-aware scoring, verification, and human approval in one tenant-isolated workspace.

The platform produces research briefs and exportable email and LinkedIn drafts. It deliberately does not send outreach, automate social actions, or represent an opportunity score as purchase probability.

What IntentGraph does

1. Define the offer. Capture a seller website, product document, targeting preferences, exclusions, and writing guidance. Extracted facts retain their exact supporting evidence and must be reviewed before release.
2. Collect authorized evidence. Upload private files, register safe public URLs, or monitor SAM.gov opportunities, Greenhouse jobs, and GitHub releases through versioned connectors.
3. Compile documents. Preserve native structure where possible, apply OCR only to eligible text regions, and use typed vision only for bounded graphical semantics or text recovery.
4. Extract signals. Convert source versions into typed observations with citations, uncertainty, lifecycle state, and reliability metadata. Unsupported claims fail the evidence gate.
5. Resolve companies. Match mentions through verified identifiers, aliases, and deterministic rules; route ambiguity and hard conflicts to an entity-review queue.
6. Build opportunities. Freeze eligible evidence into versioned sets, calculate a deterministic time-aware score, and report evidence confidence separately.
7. Verify and review. Run bounded claim verification, preserve uncertainty, and require explicit human decisions for opportunities and generated outputs.
8. Publish approved results. Export the immutable approved bundle as Markdown, PDF, JSON, or CSV.

Platform capabilities

Evidence and document intelligence

• Immutable byte objects, logical versions, acquisition lineage, content hashes, and extraction runs.
• Upload and safe-fetch support for PDF, DOCX, PPTX, XLSX, PNG, JPEG, WebP, HTML, and plain text.
• Adaptive PDF, Office, and image processing with native-first extraction, regional OCR, table structure, typed vision, and explicit unresolved states.
• Exact PDF evidence viewing with normalized coordinates, highlighted citation spans, extracted blocks, route coverage, and version history.
• Tenant-filtered hybrid retrieval over lexical rank and local 384-dimensional feature-hash embeddings stored in pgvector.

Research and review

• Evidence-backed offer compilation with immutable versions, fact-level approval, and release gates.
• Durable SAM.gov, Greenhouse, and GitHub monitoring with pause, resume, retry, and visible fetch history.
• Typed signal extraction, cross-source reasoning, company merge/split/correction history, and human reconciliation.
• Deterministic opportunity scoring with temporal decay, contradiction handling, frozen evidence sets, rebuild history, and confidence labels.
• Separate entity, opportunity-verification, and generated-output review boundaries.
• Approved research briefs, evidence-bound claims, and editable email/LinkedIn drafts with no send capability.

Workspace and operations

• Better Auth accounts, email verification, invitations, sessions, and workspace switching.
• Owner, researcher, reviewer, and viewer roles backed by explicit permissions and PostgreSQL row security.
• Workspace-scoped database transactions, object keys, workflow authority, caches, and telemetry.
• Append-only, redacted audit history; portable workspace export; and durable workspace deletion with recent-authentication and cancellation controls.
• Coarse liveness/readiness endpoints, structured redacted logging, OpenTelemetry traces, cost and token budgets, and fail-closed version registries.

Architecture

Only the web application and document extractor are deployable application services. Supporting packages remain in-process libraries with explicit dependency boundaries.

flowchart LR
    User[Researcher or reviewer] --> Web[Next.js web application]

    Web --> Auth[Better Auth and workspace RBAC]
    Web --> DB[(PostgreSQL and pgvector)]
    Web --> Store[(S3-compatible object storage)]
    Web --> Jobs[Durable PostgreSQL-backed workflows]

    Jobs --> Sources[SAM.gov, Greenhouse, and GitHub]
    Jobs --> Extractor[FastAPI document extractor]
    Jobs --> AI[Local extractive models and bounded verification]

    Extractor --> Store
    Extractor --> Vision[Credential-isolated typed vision broker]
    Vision --> Providers[Gemini or OpenAI]

    Web --> Telemetry[OpenTelemetry collector]
    Jobs --> Telemetry
    Extractor --> Telemetry

Loading

Layer	Main technologies
Web	Next.js 16, React 19, TypeScript 6, Better Auth, AI SDK
Data	PostgreSQL 18, pgvector, Drizzle ORM, SeaweedFS S3
Workflows	Durable workflow runs with a PostgreSQL world
Extraction	Python 3.13, FastAPI, Docling, PDFium, PaddleOCR, OpenCV, ONNX Runtime
Observability	OpenTelemetry and Pino
Quality	Vitest, pytest, Playwright, Ruff, mypy, ESLint, and Prettier

Getting started

Prerequisites

• Docker Desktop or another Docker Compose implementation
• Node.js 24.18.0 and pnpm 11.13.0 through Corepack
• Python 3.13.13
• uv 0.11.8

The exact Node and Python versions are recorded in .node-version and .python-version; JavaScript and Python dependencies are locked in pnpm-lock.yaml and services/extractor/uv.lock.

Bootstrap

corepack enable
corepack prepare pnpm@11.13.0 --activate
corepack pnpm install --frozen-lockfile
uv sync --project services/extractor --frozen

Copy-Item .env.example .env.local

corepack pnpm infra:up
corepack pnpm storage:bootstrap
corepack pnpm db:migrate
corepack pnpm workflow:bootstrap
corepack pnpm extractor:models
corepack pnpm dev

On macOS or Linux, replace Copy-Item .env.example .env.local with cp .env.example .env.local.

Open http://127.0.0.1:3000. The web application and extractor run on ports 3000 and 8001; PostgreSQL, S3-compatible storage, and OpenTelemetry are supplied by Compose.

scripts/run-with-example-env.mjs loads .env.example, then optional .env and .env.local files, then existing process variables. Later sources take precedence. The example values are local-only; never commit real credentials.

Optional live integrations

The application and synthetic demo work without external model calls. Configure these only for the live paths you intend to exercise:

• SAM_API_KEY for live SAM.gov opportunity checks.
• GITHUB_TOKEN for authenticated GitHub API capacity; approved public repositories can be read without it.
• VISION_PROVIDER=gemini with GEMINI_API_KEY, or VISION_PROVIDER=openai with OPENAI_API_KEY, for typed region-scoped vision.
• A pinned LibreOffice executable, font pack, and sandbox launcher for production Office previews.

See .env.example for the complete local configuration and docs/operations/LOCAL_DEVELOPMENT.md for ports, recovery, and safe-failure behavior.

Explore the complete demo

The frozen SafeCloud/FastCart fixture is synthetic and makes no live provider calls. It seeds three personas, an approved offer, SAM.gov/Greenhouse/GitHub evidence, a resolved company, three validated signals, one approved opportunity, one approved result, and all four export formats.

With infrastructure bootstrapped:

corepack pnpm demo:seed
corepack pnpm demo:verify
corepack pnpm dev

Sign in with nadia@safecloud.test and the local DEMO_ACCOUNT_PASSWORD from your environment. The other personas and expected records are documented in fixtures/demo/safecloud-fastcart-v1/manifest.json.

Useful demo lifecycle commands:

corepack pnpm demo:reset
corepack pnpm demo:clean-local

demo:clean-local is intentionally limited to confirmed local test data. It cannot be used as a production reset.

Verification

Purpose	Command
Formatting, linting, types, registries	corepack pnpm verify:static
TypeScript and Python tests	corepack pnpm test
Browser and accessibility flows	corepack pnpm test:browser
Frozen evaluation corpora	corepack pnpm evals:validate
Generated OpenAPI client drift	corepack pnpm openapi:check
Clean, populated, and idempotent migrations	corepack pnpm db:test:migrations
Durable interruption and tenant isolation	corepack pnpm workflow:smoke and corepack pnpm workflow:test:tenancy
Secrets, dependencies, and licenses	corepack pnpm verify:security
Full repository gate	corepack pnpm verify
Release evidence certification	corepack pnpm certify:phase14

The full gate starts local infrastructure, runs migrations against disposable databases, validates generated contracts and frozen evaluations, builds both services, and launches Chromium. It is substantially heavier than the static and unit checks.

Security and trust boundaries

IntentGraph assumes source content, uploaded files, connector payloads, model output, and URLs are untrusted.

• Authorization is enforced at the page/action boundary, in workspace-scoped services, and through PostgreSQL row-level security.
• Durable jobs receive a signed, expiring run context instead of broad user credentials.
• The extractor uses rotated JWT key identifiers and accesses only authorized object keys.
• URL ingestion rejects unsafe destinations and redirects; Office handling is bounded and sandboxed.
• Prompts, schemas, models, extraction profiles, and score rules are versioned. Unknown or blocked identifiers fail closed.
• Models cannot grant permissions, change deterministic scores, publish results, or bypass human review.
• Logs and health responses exclude credentials, source text, prompts, provider payloads, signed URLs, personal data, and internal configuration.

For the recorded design decisions and operational recovery procedures, see docs/decisions and docs/runbooks.

Repository layout

Path	Responsibility
apps/web	Product UI, authentication, HTTP boundaries, server actions, and storage adapter
services/extractor	Authenticated document inspection, extraction, OCR, rendering, and vision routing
packages/domain	Pure contracts, state machines, validation, scoring, and rendering algorithms
packages/db	Drizzle schemas, tenant repositories, migrations, and persistence tests
packages/workflows	Durable ingestion, source, signal, entity, opportunity, verification, and lifecycle workflows
packages/ai	Versioned local extractive models, prompts, verification, and typed vision adapters
packages/connectors	Versioned SAM.gov, Greenhouse, and GitHub connectors and normalizers
packages/evals	Frozen datasets, validators, and deterministic baselines
packages/observability	Structured logging, tracing, telemetry, and redaction
fixtures	Immutable synthetic documents, connector payloads, and golden evaluation inputs
infra	Local PostgreSQL, object storage, and telemetry configuration
docs	ADRs, operations, runbooks, compliance notes, and acceptance evidence

Contributing

Read CONTRIBUTING.md before changing architecture, generated contracts, migrations, fixtures, or security boundaries. Use forward-only migrations and create new immutable fixture versions instead of rewriting frozen inputs.

License

This repository is currently marked UNLICENSED and does not include an open-source license.