# Public Entrypoint Scan Plan

Date: 2026-03-30

## Goal

Identify deployment-side public or externally reachable entrypoints first, then use those entrypoints to locate the corresponding backend services and interface artifacts.

This scan exists because "which services are actually exposed to users" is primarily a deployment question, not a pure source-code question.

## Why This Matters

For deployment structure analysis, one of the most important unanswered questions is:

- which services are truly exposed outside the cluster
- how users enter the system
- which backend objects sit behind those entrypoints
- where the corresponding interface sets live in the KB

Without this layer, interface inventories are useful but still incomplete for answering:

- "what can users actually call"

## Core Principle

Use deployment manifests to identify exposure surfaces first.

Then connect those surfaces to:

- deployment objects
- source repos
- interface artifacts

The direction should be:

`deployment exposure -> backend service -> deployment object -> source repo -> interface artifacts`

not:

`all source interfaces -> guess which ones are public`

## Scope For The First Pass

Scan only the strongest deployment-side exposure signals:

1. `Ingress`
2. `HTTPRoute`
3. `GRPCRoute`
4. `Gateway`
5. `Service` where `spec.type` is:
   - `LoadBalancer`
   - `NodePort`

Ignore weaker or indirect evidence in v1:

- random config values mentioning hostnames
- internal service DNS only
- code-only route registrations without deployment exposure evidence

## Initial Heuristics

### Exposure Surface Classification

- `ingress`
- `httproute`
- `grpcroute`
- `gateway`
- `loadbalancer_service`
- `nodeport_service`

### Reachability Classification

Use heuristic labels, not false certainty:

- `public_dns`
- `private_dns`
- `internet_facing_lb`
- `internal_lb`
- `gateway_routed_unknown_host`
- `unknown`

### Public Candidate Rules

Treat these as strong public or externally reachable candidates:

- ingress host under domains like `tidbcloud.com` or `tidbapi.com`
- ingress with externally meaningful hostnames
- load balancer services with no explicit internal-only scheme
- explicit internet-facing ALB/NLB annotations
- gateway routes that clearly attach to shared gateway infrastructure

Treat these as non-public or lower-confidence:

- internal load balancers
- private link or private DNS style hosts
- templated/example hosts
- service-only objects without external exposure primitives

## Outputs

### Construction Output

- `construction/public-entrypoint-scan-plan.md`

This document records the scan strategy and intended artifact model.

### Knowledge Outputs

- `knowledge/deployment/public-entrypoint-catalog.json`
- `knowledge/deployment/public-entrypoint-scan.md`

`public-entrypoint-catalog.json` should be machine-readable.

`public-entrypoint-scan.md` should summarize:

- counts
- exposure-type distribution
- high-signal public candidates
- important caveats

## Required Fields For The Catalog

Each record should contain at least:

- `entrypoint_id`
- `deployment_object`
- `component_path`
- `source_repo`
- `exposure_surface`
- `reachability`
- `host`
- `path`
- `port`
- `protocol`
- `backend_service`
- `namespace`
- `environment_hint`
- `source_file`
- `evidence_kind`
- `interface_artifacts`
- `notes`

## Mapping Enrichment

The deployment-side records should be enriched from:

- `knowledge/deployment/app-delivery-object-mapping.json`

This gives:

- deployment object -> source repo

Then add repo interface artifacts from:

- `knowledge/repos/{repo}/interfaces/*.json`

This is not yet exact per-service matching, but it is enough for a first "where to look next" catalog.

## Important Limitations

The first-pass scan will still have known gaps:

1. a deployment object may have multiple internal binaries, so interface artifacts may be broader than the exact backend service
2. gateway-routed entries may not contain explicit hostnames in the local manifest
3. public exposure through shared gateways may require additional gateway config joins
4. portal/BFF layers may still be missing exact method-level coverage
5. some Helm or templated manifests must be filtered to avoid example or placeholder hosts

## Execution Plan

### Step 1

Implement a repeatable scanner under `construction/` that walks local `app-delivery` manifests.

### Step 2

Generate the first machine-readable catalog under `knowledge/deployment/`.

### Step 3

Generate a short markdown summary with the strongest findings.

### Step 4

In a later pass, improve precision by joining:

- gateway parents
- app-registry scope information
- environment matrix placements
- exact service-to-binary mapping

## Success Criteria For First Pass

The first pass is successful if it can already answer:

1. which deployment objects have obvious external entrypoints
2. which hosts and paths are visible from deployment manifests
3. which objects are definitely internal-only load balancers
4. which source repos likely own the exposed objects
5. where the candidate interface artifacts for those objects live

## Non-Goals For First Pass

Do not try to solve all of these immediately:

- exact user-facing product taxonomy
- exact auth model for every route
- complete route-to-method matching
- complete domain ownership model
- full gateway join resolution across every shared gateway layer