diff --git a/README.md b/README.md index 82ceeab..3bda982 100644 --- a/README.md +++ b/README.md @@ -1,83 +1,161 @@ -# Joblantern +

+ Joblantern — an agentic AI system that protects job seekers from recruitment fraud +

+ +

+ CI + License: Apache 2.0 + Go 1.25+ + Status: pre-alpha + 16 MCP servers +

+ +

+ Joblantern takes a job listing — a URL, a recruiter message, an offer letter —
+ and returns a sourced, reproducible verdict on whether it is safe.
+

+ +--- + +## The problem + +Every year, migrant workers and first-time job seekers lose **billions** to +fraudulent recruiters, fake licensing fees, and trafficking-adjacent schemes +that look completely legitimate on the surface. The tools needed to expose +them — company registries, domain history, scam databases, salary benchmarks, +recruitment-fee law — already exist and are mostly free and open. They are +simply not stitched together, and they are not in the hands of the people at +risk, in the language they speak, on the device they own. + +**Joblantern stitches them together** behind a single question: *is this job real?* + +## How it works + +A submission is fanned out to a panel of specialist sub-agents — each wrapping +one open data source through the Model Context Protocol — whose findings are +fused by a deterministic risk engine into one of three bands. Every signal +cites its source, and every verdict is reproducible. + +

+ Joblantern verification pipeline architecture +

+ +| Stage | What happens | +|-------|--------------| +| **Submit** | A URL, pasted recruiter message, or offer letter — via web, kiosk, bot, or REST/GraphQL API. | +| **Orchestrate** | The agent fans the submission out to MCP sub-agents in parallel. | +| **Investigate** | `pattern` (red-flag language), `address` (geocode + map via Nominatim), `registry` (company exists?), `domain`, `salary`, `law`/`routing`, `scam-db`, and adjacent-domain packs. | +| **Score** | A deterministic engine fuses weighted, sourced facts into a **green / amber / red** band with a confidence figure. | +| **Verdict** | A reproducible result with cited evidence, an optional map of the claimed office, and a publicly verifiable signature. | + +## Highlights + +- 🔎 **Evidence, not opinions** — every verdict lists weighted facts with the + tool and source that produced them. Nothing is a black box. +- 🗺️ **Geospatial verification** — the claimed office address is geocoded and + shown on an OpenStreetMap map; addresses that do not resolve count against + the listing. +- 🧩 **16 MCP servers** — each open data source is an independent, swappable + MCP server; deployments enable only what they need. +- 🌐 **Built for the frontline** — multilingual UI, no-JS "lite" mode for + hostile networks, embassy kiosk mode, caller-ID lookups, and a one-tap + panic-wipe. +- 🔬 **Open by design** — anonymized research API (REST + GraphQL), a public + knowledge graph, regulator integration, and citable annual archives. +- 🛡️ **Accountable** — a Trust & Safety Council governs appeals, a hash-chained + audit log backs every action, and a continuous red-team probes the agent. + +## Project status + +**Pre-alpha, under active development.** Interfaces and schemas may change. +See [`docs/ROADMAP.md`](docs/ROADMAP.md) and +[`docs/ROADMAP-EXTENDED.md`](docs/ROADMAP-EXTENDED.md) for the full plan. + +## Tech stack + +| Layer | Choice | +|-------|--------| +| **Language** | Go 1.25+ | +| **Agent** | Multi-agent orchestrator over the [official MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk) | +| **Web / API** | `chi` router · server-rendered templates · REST + GraphQL | +| **Data** | PostgreSQL 16 + PostGIS + pgvector | +| **Geo** | Self-hosted Nominatim + Overpass (OpenStreetMap) | +| **Maps** | Leaflet (self-hosted) on OSM tiles | +| **Observability** | Prometheus + structured `slog` | + +Architectural decisions are recorded in [`docs/ADR/`](docs/ADR/). -[![CI](https://github.com/yasserrmd/joblantern/actions/workflows/ci.yml/badge.svg)](https://github.com/yasserrmd/joblantern/actions/workflows/ci.yml) -[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0) -[![Go Version](https://img.shields.io/badge/go-1.23%2B-00ADD8.svg)](https://go.dev/dl/) -[![Status: pre-alpha](https://img.shields.io/badge/status-pre--alpha-orange.svg)](#status) - -> **An agentic AI system that protects job seekers from fraudulent -> employers, fake listings, and exploitative recruitment schemes.** - -Joblantern takes a job listing — a URL, a recruiter message, an offer -letter — and runs it through a multi-agent verification pipeline that -checks the company's registration, the domain's history, public scam -databases, salary plausibility, and recruitment-fee legality in the -destination country. Every signal cites its source and every verdict -is reproducible. - -## Why +## Quickstart -Migrant workers and first-time job seekers lose billions every year to -fraudulent recruiters, fake licensing fees, and trafficking-adjacent -schemes that look completely real on the surface. The tools to verify -a recruiter already exist and are mostly free and open. They are just -not stitched together. Joblantern stitches them together. +### Docker (recommended) -## Status +```bash +git clone https://github.com/yasserrmd/joblantern.git +cd joblantern -Pre-alpha. Active development. +# Postgres + the address sub-agent + the app +docker compose -f deploy/docker-compose.smoketest.yml up -d --build +``` -## Stack +Open **http://localhost:18080** and submit a listing. Tear down with: -- **Backend:** Go 1.23+ -- **Agent framework:** [Google ADK for Go](https://github.com/google/adk-go) -- **MCP:** [Official Go SDK](https://github.com/modelcontextprotocol/go-sdk) -- **Database:** PostgreSQL 16 -- **Web:** chi + templ + HTMX + Tailwind CSS -- **Observability:** OpenTelemetry + Prometheus + slog +```bash +docker compose -f deploy/docker-compose.smoketest.yml down -v +``` -See [`docs/ADR/`](docs/ADR/) for locked architectural decisions. - -## Quickstart +### Local build ```bash -# clone -git clone https://github.com/yasserrmd/joblantern.git -cd joblantern - -# environment cp .env.example .env +make docker-up # bring up Postgres +make migrate-up # run migrations +make build && ./bin/joblantern +``` -# bring up postgres -make docker-up +Visit `http://localhost:8080/healthz` — you should see `ok`. -# run migrations -make migrate-up +## Try the API -# build and run -make build -./bin/joblantern +```bash +curl -s -X POST http://localhost:18080/api/v1/verify \ + -H 'Content-Type: application/json' \ + -d '{ + "listing_text": "URGENT driver wanted Dubai AED 18000, send AED 2500 processing fee via Western Union, no interview, WhatsApp only", + "company_name": "QuickJobs Gulf", + "claimed_address": "Business Bay Tower, Dubai", + "jurisdiction": "AE" + }' +# → { "verification_id": "…" } then GET /api/v1/verifications/ ``` -Visit `http://localhost:8080/healthz` — you should see `ok`. +The verdict comes back **red** with cited red-flag evidence (extraordinary pay, +wire-only fee, no interview) and — if the address resolves — a map pin. -## License +## Documentation -Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE). +| Area | Docs | +|------|------| +| Architecture & decisions | [`docs/ADR/`](docs/ADR/) | +| Self-hosting | [`docs/SELF-HOSTING.md`](docs/SELF-HOSTING.md) · [`docs/SCALING-RUNBOOK.md`](docs/SCALING-RUNBOOK.md) | +| Research & data | [`docs/RESEARCH-API.md`](docs/RESEARCH-API.md) · [`docs/KNOWLEDGE-GRAPH.md`](docs/KNOWLEDGE-GRAPH.md) | +| Frontline modes | [`docs/EMBASSY-KIOSK.md`](docs/EMBASSY-KIOSK.md) · [`docs/CALLER-ID.md`](docs/CALLER-ID.md) · [`docs/HOSTILE-NETWORK.md`](docs/HOSTILE-NETWORK.md) | +| Governance | [`docs/GOVERNANCE.md`](docs/GOVERNANCE.md) · [`docs/COUNCIL-CHARTER.md`](docs/COUNCIL-CHARTER.md) · [`docs/TRANSPARENCY.md`](docs/TRANSPARENCY.md) | +| Compliance | [`docs/COMPLIANCE/`](docs/COMPLIANCE/) (GDPR / DPDPA / PDPL) | -Every dependency must be Apache 2.0, BSD, MIT, or another permissive -license — no GPL, AGPL, LGPL, SSPL, BUSL, or Elastic License code may -ship in the Joblantern binary. +## License -## Contributing +Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE). -See [CONTRIBUTING.md](CONTRIBUTING.md). All contributions are accepted -under the Developer Certificate of Origin (DCO). +Every dependency that ships in the Joblantern binary must be permissively +licensed (Apache 2.0, BSD, MIT). No GPL, AGPL, LGPL, SSPL, BUSL, or Elastic +License code may be linked in. -## Security +## Contributing & security -See [SECURITY.md](SECURITY.md) for vulnerability disclosure. +- Contributions are accepted under the Developer Certificate of Origin — see [CONTRIBUTING.md](CONTRIBUTING.md). +- Report vulnerabilities per [SECURITY.md](SECURITY.md). +- Community expectations: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). ## Author -Mohamed Yasser — Solutions Architect. +**Mohamed Yasser** — Solutions Architect. diff --git a/docs/assets/architecture.png b/docs/assets/architecture.png new file mode 100644 index 0000000..eadfd33 Binary files /dev/null and b/docs/assets/architecture.png differ diff --git a/docs/assets/banner.png b/docs/assets/banner.png new file mode 100644 index 0000000..319cab6 Binary files /dev/null and b/docs/assets/banner.png differ