Repository maps

← Visual assets · Documentation home · Architecture · Diagram source

European Tech Opportunities 2027 turns permission-gated public listing evidence into a validated directory. SQLite owns the lifecycle; the website, API, downloads, and README only present it.

The maps use colored subsystem groups, labeled connections, database shapes, and clickable implementation links, inspired by GitDiagram. They describe the checked-in architecture, not production data or a live deployment.

Choose a view

View	Question it answers
Repository overview	How does the whole system fit together?
Collection and lifecycle	How does evidence become an accepted listing?
Website and publication	What reaches users, and what stays in their browser?
Automation and deployment	How does reviewed state reach production safely?
Testing, documentation, and tooling	What builds, verifies, documents, and protects the project?
Editable Mermaid source	Where do I change or reuse these diagrams?

Viewing: open an SVG directly in your browser to zoom and follow its code links. On GitHub, use the raw/download view; embedded image previews may disable node links. The SVGs work without JavaScript, a diagram service, API keys, or external resources. Code links open GitHub only when selected and target main, which may differ from the revision you are viewing.

Legend: solid arrows carry data, evidence, or artifacts; dashed arrows mean “runs,” “configures,” or “supports.” Cylinders represent stored data; the hexagon identifies the controlled application writer, and diamonds mark publication gates. Grouped boxes are ownership boundaries, not necessarily separate services. Python paths are relative to src/opportunities/ unless shown in full.

Repository overview

Open the full-size repository map

Read the main path as configure → collect → classify → persist → publish. Search definitions and acceptance rules tell the CLI where to look and what evidence is required. The Python pipeline rotates searches by persistent completion time, fetches permitted guest HTML, and applies deterministic acceptance checks. Only Repository writes application state, keeping lifecycle evidence, search rotation, and aggregate quality baselines in SQLite.

HTTP 429 stops subsequent source requests. Independently completed searches or confirmed availability checks may qualify for HTTP 429-only partial publication only after every required gate passes; the resulting proposal requires manual review and merge.

The website, API, downloads, and bounded README present that state; production readers use verified releases. Browser-local lists sit beside the public data flow and never write back to the database. The surrounding groups show the automation, tests, documentation, policies, and build tools supporting these boundaries.

Collection and lifecycle

Open the collection map · Acceptance policy · Lifecycle details

Search YAML defines discovery scope; classification rules define publication eligibility. The CLI supplies validated settings to a runner that bounds concurrency and isolates each search. Never-completed and oldest-completed searches run first, with stable registry ties; denied and skipped searches retain priority. Permission-gated HTTP provides search cards and identity-validated details, with company/title prefilters first. Normalization and classification check role type, seniority, technology, cycle/date, and European location. Successful searches commit independently with their completion timestamps; failed and skipped searches save diagnostics without lifecycle evidence or scheduling advancement.

Full, partial, and blocked outcomes remain distinct. HTTP 429 partial candidates require at least one completed search, only HTTP 429 failures or source-skipped searches, and every publication gate. Any other search failure blocks publication, even alongside a rate limit. Only successful, nonblocking full-registry collections establish quality baselines.

Missing cards cannot close jobs. Known-ID rechecks require repeated explicit 404/410 confirmations; closure occurs only after no active search association remains. The collection map shows the built-in availability default: at most 50 due jobs, with a five-day minimum interval. Production automation recommends the Actions variable OPPORTUNITIES_AVAILABILITY_MAX_JOBS=100 for scheduled audits; the software default remains unchanged. It keeps or reopens valid listings, deletes explicitly unavailable ones, and preserves inconclusive rows. An HTTP 429-only partial audit requires completed confirmed checks and no independent failures, skips scraping, and passes validation for manual review. Other audit source stops block publication.

Reviewed offline additions reuse acceptance checks and repository transactions, without invented provenance or manual reopening.

Website and publication

Open the publication map · Website contract · Public data

SQLite feeds two publication paths: Python-generated files and server-only website queries. Python owns the README preview, full-state review seal, sanitized CSV/JSON, and dataset metadata. The README projection node includes English and the five localized READMEs in docs/translations/: all six share canonical counts, seals, and bounded listing data, with localized presentation labels and UTC date displays. The renderer preserves authored text and reciprocal language selectors outside those regions. The Next.js page, v1 listing API, and RSS/Atom feeds share a read-only query; download routes only serve existing export files. The status endpoint separately reads successful-collection time and open counts, then verifies bounded metadata against the streamed JSON download hash. In versioned mode, each server operation selects one release before opening its database or downloads.

React components handle search, filters, sorting, pagination, and theme without changing canonical data. Saved/applied/hidden IDs and visit times stay in localStorage, never SQLite, shared URLs, the API, or analytics. Schema, link-validation, and metadata helpers keep the public output predictable and safe to consume.

Automation and deployment

Open the operations map · Canonical automation guide

Scheduled and manual workflows serialize canonical updates through a shared one-writer lock. The nightly node shows the default audit → scrape sequence. Manual runs can set skip_availability=true to select scraping only; scheduled runs always audit. An eligible HTTP 429 partial audit skips scraping and proceeds only through validation and manual-review handoff. The protected processor restores verified state, migrates, requires its README to match reviewed main, and runs selected CLI phases. Full and eligible HTTP 429 partial results must pass SQLite integrity and projection checks before checkpointing and restricted snapshot publication. Collection also requires its aggregate quality gate; audit-only partials never fabricate collection metrics or reports. Round-trip snapshot verification must succeed before the README handoff. Search rotation travels with the database, never a separate queue or artifact.

A separate job receives only the six public README projections and outcome output, opens a pull request restricted to their explicit path allowlist, and waits for validation. Only the English README controls the reviewed-state barrier; localized projections cannot approve mismatched canonical state. Fully successful nightly collections retain the existing automatic-merge policy; partial proposals use a labeled -partial branch and require manual review and merge. Unmerged or rejected partial snapshots still block ordinary subsequent mutation and deployment at the reviewed-state barrier. Merging the matching README does not deploy: publication is a separate protected manual run.

Deployment verifies payloads under a lock and switches the release pointer atomically, retaining old releases for readers. Canonical databases and snapshot manifests never enter public GitHub caches or artifacts. Recovery modes differ: the normal drill publishes a verified snapshot; seal adoption and README recovery propose only README changes for review.

Testing, documentation, and tooling

Open the foundations map · Testing guide · Documentation ownership

These groups explain how the repository is built and checked without accessing live listing data. Frozen Python and Bun dependencies provide consistent linting, typing, unit tests, and browser tooling. Domain models, shared utilities, migrations, and public schemas define the contracts those checks protect. Offline fixtures and synthetic SQLite/exports drive integration, browser, accessibility, and privacy tests. CI adds container smoke tests and security checks; normal validation never collects LinkedIn listings. Documentation and sanitized visuals use a separate allowlisted build, publishing to GitHub Pages only from main. Coverage and registry summaries come from their owning tools, while policies and contribution controls guide review.

Repository coverage

Repeated search definitions, tests, and small UI primitives are grouped so the maps stay readable. Together these views cover the maintained repository at subsystem level, not every file or import.

Area	Included responsibilities
configs/	Company/country/role searches, categories, example settings
src/opportunities/cli/, config/	Entry point, commands, settings, search registry, rules, cycle policy
src/opportunities/scrapers/	Bounded HTTP transport and LinkedIn guest parsing
src/opportunities/normalization/, pipeline/	Title/location normalization, acceptance, rotating collection, aggregate quality gates, bounded availability
src/opportunities/models/, utils/	Typed records/enums; concurrency, atomic files, paths, time, text, URL, logging
src/opportunities/database/, migrations/, alembic.ini	Repository, SQLAlchemy models/sessions, schema history, verified snapshots
Python projection modules	readme.py, readme_localization.py, public_exports.py, search_registry_docs.py
schemas/	Public v1 schema and sanitized contract examples
site/src/app/, components/, lib/, types/	Routes, directory UI, theme/layout, server queries, browser state, helpers, metadata
site/scripts/, site configuration	Standalone startup, synthetic demo recording, Next.js/security headers, browser/Lighthouse tooling
tests/, site/tests/, scripts/testing/	Unit/integration/benchmark coverage, fixtures, synthetic state, browser accessibility and privacy checks
scripts/database/, scripts/deployment/	Migration checks, backup/bootstrap/recovery, snapshot transfer, locked release activation
.github/	Workflows, shared Python setup action, issue/PR templates, owners, Dependabot, prose rules
docs/, scripts/docs/, mkdocs.yml	User/maintainer guides, visual assets, link/lint/build checks, coverage documentation, Pages
Root tooling and policies	Python/Bun manifests and locks, Makefile, Docker/Compose, ignore/lint settings, contribution/security/privacy/community/license rules
data/	Ignored runtime SQLite, generated exports, and versioned release files; shown conceptually, never read or included in these assets

Vendored dependencies, build outputs, caches, local logs, secrets, private databases, and personal .context/ or .agents/skills/ content are intentionally excluded.

Maintain the maps

Edit the relevant block in source.md, then regenerate its SVG using the rendering profile. The five SVGs in svg/ are rendered artifacts of that source; the README and editable source stay at this folder's root. Keep diagram source and rendered SVGs in this folder; changes to product-showcase media follow the separate asset guide.

Check Mermaid parsing, code-link targets, text containment, SVG accessibility labels, and readability at both preview and full size. Include group headings in overlap checks: they must clear the first component box and remain inside their group. SVGs must remain self-contained: no scripts, HTML labels, embedded credentials, or runtime data. The canonical architecture, security policy, and linked maintainer guides remain authoritative if implementation changes make a map stale.