ForgeRank
GitHub

Documentation / engineering contract

How ForgeRank
reasons.

A compact guide to the acquisition boundary, append-only evidence model, versioned scoring, local operation, and verification. The repository remains the source of truth.

01 / Operating model

Useful before impressive.

ForgeRank is an open-source intelligence platform for repository rankings, momentum, engineering activity, discovery, comparison, and ecosystem analysis. Its core product works without GitHub credentials or external AI services.

The product becomes more useful as its own observation history accumulates. Before a defensible history exists, the UI exposes an insufficient-data state rather than substituting current stars, reconstructed history, or an industry average.

Core rule

Observation and inference stay separate. Missing evidence remains missing.

02 / Source boundary

Public, bounded, policy-aware.

Allowed sources

  • Public GitHub HTML documents when robots policy permits automated access.
  • Public repositories through normal HTTPS Git transport.
  • Public repository files read through a bounded partial clone.
  • ForgeRank’s own historical observations and derived aggregates.
  • Version-controlled identifiers and curated repository collections.

Prohibited paths

No REST API, GraphQL API, tokens, OAuth, authenticated sessions, hidden JSON endpoints, IP rotation, bot-protection evasion, commercial data APIs, or external embeddings. A static architecture guard scans runtime and dependency files in CI.

Failure behavior

Unavailable robots policy fails closed. Rate limits pause acquisition. Parser mismatches do not persist malformed values, and cached observations remain readable.

03 / System boundaries

Dependencies flow inward.

Layer Responsibility
src/app + src/components Presentation and product interaction
src/application Use cases and bounded read models
src/domain Pure policy, scores, trends, and classification
src/infrastructure PostgreSQL, public documents, Git, queue, and logs
src/worker Long-running collection and calculation orchestration

Evidence flow

  1. Identifiers or validated submissions create canonical repository records.
  2. A deduplicated PostgreSQL job records priority, availability, and retry policy.
  3. The worker checks source policy, persistent budgets, circuits, and cache.
  4. Versioned parsers validate structure and normalize observed fields.
  5. A transaction updates the current projection and appends historical evidence.
  6. Bounded Git inspection enriches activity, technology, and repository structures.
  7. Versioned domain services persist scores, reasons, lifecycle, and rankings.

04 / Repository score v1

Six dimensions, one explained total.

Dimension Maximum Primary inputs
Impact 25 Log-normalized stars, forks, available longevity
Momentum 20 Absolute growth, relative growth, acceleration
Health 20 Commit freshness, active weeks, observed file structures
Community 15 Non-bot Git-author depth and distribution
Engineering 10 Sustained activity and maintenance infrastructure
Trust 10 Evidence confidence minus cautious anomaly penalties

The dimension sum is multiplied by the observation-confidence factor: 1.00, 0.92, 0.75, or 0.50. Every calculation persists one structured positive, neutral, caution, or missing reason for each dimension, together with raw observed inputs.

Interpretation boundary

File presence and Git activity are evidence inputs. They do not prove correctness, security, code quality, maintainer intent, or individual worth.

05 / Repository similarity v2

Related means shared evidence.

Similar repositories are calculated deterministically on a fixed 100-point scale: primary language 25, classified-topic overlap 25, detected-technology overlap 20, bounded description-keyword overlap 15, curated-collection overlap 10, and shared known lifecycle 5.

Missing dimensions earn zero rather than having their weight redistributed. Matches below 15 are not published. This is evidence overlap—not a semantic AI judgment or a quality claim.

06 / Local development

One root entrypoint.

Requirements are Node.js 22+, Git 2.40+, and network access only when public-data indexing is explicitly requested. The default first run makes no GitHub request.

QUICK START 
git clone git@github.com:OthmaneBlial/ForgeRank.git
cd ForgeRank
./run.sh

Optional explicit enrichment

INDEX A BOUNDED SAMPLE 
pnpm forge bootstrap --limit 12
pnpm forge inspect solidjs/solid
pnpm forge rank

07 / Quality gates

Test the claims.

ForgeRank’s CI separates static quality, PostgreSQL integration, browser behavior, and Docker smoke deployment. E2E fixtures are sanitized, deterministic, and network-free.

COMPLETE LOCAL AUDIT 
pnpm verify:zero-api
pnpm audit:dependencies
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm test:e2e
pnpm audit:performance
pnpm audit:postgres

08 / Deployment

PostgreSQL, web, worker.

The Compose stack contains PostgreSQL, a one-shot migration service, a minimal standalone Next.js web image, and a separate operations image for the CLI and worker. Application containers run as an unprivileged user under tini.

DOCKER 
docker compose up --build
docker compose run --rm worker pnpm seed

Web liveness is process-only; readiness performs a bounded database query. Worker readiness requires a fresh database-backed heartbeat. Public health responses expose no queue or acquisition internals.

09 / Evidence limits

Scope stays visible.

  • A fresh seed contains identifiers—not production analytics.
  • Weekly and monthly momentum need real retained snapshot windows.
  • Public HTML can change despite fixture tests and parser resilience.
  • Git authors are not automatically confirmed public accounts.
  • Ranks cover ForgeRank’s indexed universe, not every GitHub repository.
  • Signals do not prove quality, security, intent, or individual worth.

10 / Repository source of truth

Go deeper in the codebase.

Architecture → Data sources → Scoring → Performance → Privacy → Security → Progress → Contributing →