https://github.com/kzndotsh/gang.guide
Evidence backed mapping of criminal organizations across the US — alliances, rivalries, history, and culture.
https://github.com/kzndotsh/gang.guide
ai crime data-analysis data-science data-visualization dataset gangs konva konvajs llm organized-crime python svelte tailwind typescript
Last synced: about 5 hours ago
JSON representation
Evidence backed mapping of criminal organizations across the US — alliances, rivalries, history, and culture.
- Host: GitHub
- URL: https://github.com/kzndotsh/gang.guide
- Owner: kzndotsh
- Created: 2026-06-26T01:15:45.000Z (4 days ago)
- Default Branch: main
- Last Pushed: 2026-06-26T03:06:49.000Z (4 days ago)
- Last Synced: 2026-06-26T03:10:08.374Z (4 days ago)
- Topics: ai, crime, data-analysis, data-science, data-visualization, dataset, gangs, konva, konvajs, llm, organized-crime, python, svelte, tailwind, typescript
- Language: Svelte
- Homepage: https://gang.guide
- Size: 1.24 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
gang.guide
Evidence backed mapping of criminal organizations across the US — alliances, rivalries, history, and culture.
🌐 Live Site •
🚀 Quick Start •
🏗️ Architecture •
⚙️ Pipeline •
✅ Standards •
🗺️ Roadmap
---
## Quick Start
```bash
# Clone and setup
git clone https://github.com/kzndotsh/gang.guide.git
cd gang.guide
just setup
# Or manually:
npm install
cd apps/web && npm install
python3 build.py
# Run the dev server
just dev
```
## How It Works
```
Scrape → Clean → Extract (sonnet 4.5 × 3 temps) → Adjudicate (opus 4.6) → Merge → Apply → Build → Serve
```
1. **Scrape** raw HTML from sources into `data/raw/`
2. **Extract** structured JSON via sonnet 4.5 at 3 temperatures — edges require verbatim evidence quotes
3. **Adjudicate** with opus 4.6 — validates evidence, rejects co-mentions, resolves conflicts
4. **Merge** via algorithmic consensus (2/3 agreement) or adjudicated result
5. **Apply** conservative upgrade to `data/orgs/*.json` + `data/edges.json` — lint gates the result
6. **Build** compiles flat files into `graph.json` + `details.json`
7. **Serve** on Cloudflare Workers via SvelteKit + Konva.js canvas
## Data
Stats are computed at build time by `build.py` and embedded in `graph.json`. All relationships are evidence-backed with verbatim quotes from source material. Data quality is enforced by [lint rules](docs/STANDARDS.md) that run in CI and gate every pipeline application.
**Sources:**
| | | |
|---|---|---|
| [Wikipedia](https://en.wikipedia.org) | [StreetGangs.com](https://www.streetgangs.com) | [UnitedGangs.com](https://unitedgangs.com) |
| [Chicago Gang History](https://chicagoganghistory.com) | [DetroitStreetGangs](https://detroitstreetgangs.com) | [NGCRC](https://www.ngcrc.com) |
| [NewYorkCityGangs](https://newyorkcitygangs.com) | [StoneGreasers](https://www.stonegreasers.com) | [DOJ / FBI](https://www.justice.gov) |
| [BlackPast.org](https://www.blackpast.org) | [CourtListener](https://www.courtlistener.com) | |
## Tech Stack
| Component | Technology |
|-----------|------------|
| **Data** | Flat JSON files, Python build script |
| **Frontend** | SvelteKit 5, Konva.js, Tailwind CSS, shadcn-svelte |
| **Rendering** | Raw Konva Canvas API (persistent nodes, edge-index, directional arrows) |
| **Deployment** | Cloudflare Workers via Alchemy IaC |
| **Pipeline** | Python, sonnet 4.5 + opus 4.6 (LLM extraction) |
| **Linting** | Ruff (Python), svelte-check (frontend) |
| **Testing** | pytest + vitest, codecov coverage |
| **CI/CD** | GitHub Actions, conventional commits, lefthook |
## Project Structure
```
├── build.py # Builds graph.json + details.json from flat data
├── data/
│ ├── orgs/ # One JSON per org (source of truth)
│ ├── edges.json # Edge list (alliances, rivalries, affiliations)
│ └── lanes.json # Lane taxonomy + org anchors
├── apps/
│ ├── web/ # SvelteKit + Konva.js Canvas map viewer
│ │ ├── src/routes/ # +page.svelte (main map), sitemap.xml
│ │ ├── src/lib/map/ # KonvaMap.svelte, visibility.ts, scale.ts
│ │ ├── src/lib/inspector/ # Inspector panel components
│ │ └── alchemy.run.ts # Deployment config (Cloudflare Workers)
│ └── pipeline/ # Python LLM extraction pipeline
│ ├── extract.py # Multi-temp extraction (sonnet 4.5)
│ ├── adjudicate.py # Conflict resolution (opus 4.6)
│ ├── merge.py # Consensus filtering
│ ├── apply.py # Conservative data upgrade
│ ├── lint.py # Data validation (runs in CI)
│ └── tests/ # Unit tests + e2e + fixtures
├── .ruler/ # AI agent instructions (source of truth)
├── .github/workflows/ # CI + release + PR title validation
├── justfile # Task runner (just dev, just ci, just pipeline)
├── pytest.ini # Test config (strict markers, coverage)
├── lefthook.yml # Git hooks (ruff pre-commit, svelte-check pre-push)
├── flake.nix # Nix dev shell
├── TODO.md # Roadmap
└── docs/ # Documentation
├── ARCHITECTURE.md # System design
├── PIPELINE.md # LLM extraction pipeline
├── SCHEMA.md # Data schema reference
├── STANDARDS.md # Data quality rules & lint checks
├── TERMINOLOGY.md # Glossary
├── USER.md # User guide
└── CONTRIBUTING.md # Contributor guide
```
## Commands
```bash
just # list all tasks
just setup # bootstrap after cloning
just dev # start dev server
just build-data # rebuild graph.json from org files
just lint # lint data integrity
just check # type-check frontend
just deploy # deploy to production
just ruler # regenerate AI agent configs
```
## Adding a New Org
1. Create `data/orgs/my-new-org.json`:
```json
{
"id": "org:my-new-org",
"name": "My New Org",
"aliases": [],
"type": "street_gang",
"lane": "california-latino-other",
"metro": "Los Angeles",
"founded_year": 1985,
"founded_year_precision": "circa",
"description": "Factual 1-3 sentence description with founding context.",
"colors": ["blue"],
"nation_affiliation": null,
"status": "active",
"sources": [{"url": "https://...", "title": "Source Name"}]
}
```
2. Add relationships to `data/edges.json` if needed
3. Run `just build-data`
## Deployment
Deployed to Cloudflare Workers via [Alchemy](https://github.com/alchemy-run/alchemy).
```bash
just deploy # production
just deploy-preview # personal stage
```
Requires `apps/web/.env` with `ALCHEMY_PASSWORD`, `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`.
## AI Agent Setup
Instructions managed via [Ruler](https://github.com/intellectronica/ruler). After cloning:
```bash
just ruler
```
This generates config files for Claude, Copilot, Cursor, and Kiro from `.ruler/AGENTS.md`.
## License
TBD
## Contributors
Created by [@kzndotsh](https://github.com/kzndotsh)
## Project Stats
