BotScore

Evidence-based SEO, AEO, and GEO readiness scoring for public websites.

BotScore inspects a URL, collects reproducible evidence, and explains what may prevent search engines and AI answer engines from discovering, understanding, or citing the page. The public result uses a shareable, human-readable route such as /example.com and presents animated scores, prioritized findings, and practical fixes.

BotScore measures technical and content readiness. It does not claim to measure rankings, guaranteed citations, or real-world visibility without external platform data.

What it evaluates

• SEO readiness — HTTP behavior, redirects, crawlability, indexability, canonical URLs, sitemaps, metadata, and server-rendered content.
• AEO readiness — direct-answer structure, headings, definitions, sources, authorship, freshness, and structured data.
• GEO readiness — AI search crawler access, entity signals, citable evidence, snippet controls, and content availability.
• Trust signals — ownership, contact, policy, and accountability signals that support confident interpretation.

Every finding is generated by a versioned deterministic rule. An optional LLM integration can summarize existing evidence, but it cannot decide pass/fail states or alter scores.

Product flow

Public URL
   │
   ▼
Next.js API ──► PostgreSQL + pg-boss ──► Audit Worker
                                             │
                                             ├─ raw HTTP inspection
                                             ├─ robots and sitemap checks
                                             └─ Chromium-rendered inspection
   ▲
   │
Shareable result route: /<hostname>

The default production target is a single Ubuntu VPS running Docker Compose. Caddy terminates HTTPS; the Web service and Worker share PostgreSQL, while Chromium concurrency remains bounded so a traffic burst cannot start unlimited browser processes.

Quick start with Docker

Requirements: Docker Engine, Docker Compose, a domain pointed at the server, and ports 80/443 available.

git clone https://github.com/tentenco/BotScore.git
cd BotScore
cp .env.production.example .env

Set APP_DOMAIN, POSTGRES_PASSWORD, and RATE_LIMIT_SALT in .env, then start the stack:

docker compose up -d --build
docker compose ps
curl --fail https://your-domain.example/api/health/ready

Only ports 80 and 443 are published. PostgreSQL, the Web service, and the Worker remain on the private Compose network.

Local development

Requirements: Node.js 22.12+, pnpm 11, PostgreSQL, and Chrome or Chromium.

pnpm install
cp .env.example .env.local
pnpm db:migrate
pnpm dev

Start the durable audit worker in a second terminal:

pnpm worker

Open http://localhost:3000, submit a public URL, and follow the live audit to its shareable result page.

Quality gates

pnpm typecheck
pnpm lint
pnpm test:run
pnpm build

Configuration

Variable	Purpose	Default
DATABASE_URL	PostgreSQL connection shared by Web and Worker	local development URL
AUDIT_CONCURRENCY	Maximum simultaneous browser audits per Worker	2
AUDIT_CACHE_TTL_SECONDS	Reuse window for completed same-host results	21600
AUDIT_JOB_TIMEOUT_SECONDS	Maximum audit job duration	300
RATE_LIMIT_SALT	Secret salt for privacy-preserving request quotas	development fallback
ENABLE_OPENROUTER_NARRATIVE	Enable constrained evidence narration	false
HUBSPOT_PRIVATE_APP_TOKEN	Optional lead sync	unset
LISTMONK_URL	Optional transactional report delivery	unset

See .env.example and .env.production.example for the complete list.

Security and reliability

• SSRF protection validates public destinations and revalidates redirects.
• DNS results are pinned during each request to reduce rebinding risk.
• Response sizes, fetch times, render times, redirects, retries, and Worker concurrency are bounded.
• Audit jobs survive Web and Worker restarts through PostgreSQL-backed pg-boss queues.
• Rate-limit identities are salted and stored without raw IP addresses.
• Report links use hashed, expiring tokens.
• Secrets, local databases, generated builds, test artifacts, and backups are excluded from Git.

Documentation

• Product strategy
• Audit rules v0
• Results experience design
• Ubuntu VPS operations and scaling

License

BotScore is available under the MIT License.

Community

Questions, product feedback, rule proposals, and deployment notes belong in GitHub Discussions. Please avoid posting credentials, private reports, customer data, or non-public URLs.

BotScore is a Tenten product. Related company sites and official social channels are available from the product footer.

OpenAI Build Week 2026 — built with Codex

BotScore was designed and implemented with Codex (GPT-5.6) during the Build Week submission period. Codex was used end-to-end: drafting the product strategy and versioned audit rules, implementing the deterministic scanner and pg-boss worker pipeline, building the animated results experience, and producing the Docker Compose production stack.

Codex session IDs (local session logs, 2026-07-14, model gpt-5.6-sol):

• 019f5eaf-ca2f-7340-920b-0f3fee0755ed (11:33 — product strategy, scaffold, audit rules engine)
• 019f5f32-4e3a-71d3-a79a-6ea030c62cd6 (13:56 — scanner/worker pipeline, API routes, report gating)
• 019f5f5b-72ad-7251-b748-3629aadeb50b (14:40 — results design system, Docker/Caddy production stack, tests)

Hackathon materials (demo script, Devpost submission copy) live in hackathon/.

Judge quickstart

pnpm install
cp .env.example .env.local   # defaults work; PostgreSQL required
pnpm db:migrate
pnpm dev                     # terminal 1 — web/API
pnpm worker                  # terminal 2 — audit worker

Or run the full production stack with docker compose up -d --build (set APP_DOMAIN=localhost). Then open the app, submit any public URL, and watch the audit stream in. Quality gates: pnpm typecheck && pnpm lint && pnpm test:run && pnpm build.