Add architecture blueprint, DB schema, API design, and codebase structure for scan.run

[suresync]

Motivation

• Provide a production-oriented implementation blueprint for scan.run covering architecture, security, and operational constraints to guide development from MVP to enterprise scale.
• Define safe scanning policies, domain verification, and billing/credit models to prevent abuse while enabling the required single-scan and subscription plans.
• Supply a concrete, multi-tenant data model and API contract so engineers can implement services, workers, and report generation consistently.

Description

• Add top-level README.md describing product goals, pricing, and links to implementation docs.
• Add docs/architecture.md with service boundaries, queue/worker model, technology stack, deployment and security controls for isolated scanning.
• Add docs/database_schema.sql containing a reference PostgreSQL schema for tenants, users, projects, domains and verification, subscriptions, credit ledger, scan jobs/executions, findings, report snapshots/exports, API keys, audit logs, and rate-limit counters.
• Add docs/api.md describing public and internal API endpoints (auth, tenants, projects/domains, scans, reports, billing, webhooks) and docs/codebase-structure.md outlining an opinionated monorepo layout and extensibility patterns.

Testing

• No automated tests were added or executed as part of this change.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f0b7dd58b7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Add citext extension before using CITEXT

The schema defines users.email as CITEXT, but this file only enables uuid-ossp; on a clean PostgreSQL instance this will fail at table creation with a type "citext" does not exist error. Because this script is presented as a full reference schema, missing CREATE EXTENSION IF NOT EXISTS citext; makes initial provisioning and migrations fail unless operators add undocumented manual setup steps.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Scope scan job foreign keys by tenant

scan_jobs includes tenant_id, but project_id and domain_id each reference only the global id, so the database can accept a row where the scan's tenant differs from the referenced project/domain tenant. That breaks tenant isolation guarantees and can mix data across accounts (e.g., reporting or billing against another tenant's assets). Enforce composite tenant-scoped keys (e.g., (tenant_id, id)) and matching composite foreign keys to prevent cross-tenant linkage.

Useful? React with 👍 / 👎.