---
title: "docs: Rewrite README.md with quickstart and project overview"
type: feat
status: active
date: 2026-04-24
---

# Rewrite README.md

## Overview

The current README.md is 22 lines and only covers embeddings and Ansible deployment. It does not explain what Stemwijzer is, how to run it locally, or how to run the pipeline. New contributors must discover ARCHITECTURE.md to get oriented.

## Problem Frame

- README is the first file a visitor sees
- No quickstart instructions
- No mention of Streamlit, the voting UI, or the explorer
- No screenshot or demo link
- Missing prerequisites (Python 3.13, uv, DuckDB)

## Requirements Trace

- R1. Explain what the project does in 2 sentences
- R2. Show a screenshot or demo link
- R3. List prerequisites and installation steps
- R4. Provide quickstart commands (run app, run pipeline, run tests)
- R5. Link to ARCHITECTURE.md for deep dive
- R6. Link to docs/ for additional documentation

## Scope Boundaries

**Included:**
- Rewrite README.md with new structure

**Excluded:**
- Changing ARCHITECTURE.md (only link to it)
- Adding screenshots (placeholder path accepted)
- Creating a demo deployment

## Key Technical Decisions

- **Keep it concise** — README should be scannable in 2 minutes. Deep content lives in ARCHITECTURE.md.
- **Use the same commands as ARCHITECTURE.md** — single source of truth for commands
- **Match the project's language** — Dutch UI, English docs

## Implementation Units

- [ ] U1. **Draft and review README structure**

**Goal:** Create a README that a new contributor can follow to get the app running in <10 minutes.

**Requirements:** R1–R6

**Dependencies:** None

**Files:**
- Modify: `README.md`

**Approach:**
Structure:
1. Title + one-line description
2. Screenshot placeholder
3. What is Stemwijzer? (2 sentences)
4. Features bullet list (voting compass, explorer, analytics)
5. Prerequisites (Python 3.13, uv)
6. Quickstart (clone, uv sync, run Streamlit, run pipeline)
7. Testing (uv run pytest)
8. Project structure (brief, link to ARCHITECTURE.md)
9. Documentation links (ARCHITECTURE.md, docs/)
10. License

**Test expectation:** none — documentation-only change. Verify by reading the rendered markdown.

**Verification:**
- A new contributor can follow the quickstart without reading other files
- All commands in README match ARCHITECTURE.md
- No broken internal links

---

## Risks & Dependencies

| Risk | Mitigation |
|------|------------|
| README grows too long | Cap at ~80 lines; defer deep content to ARCHITECTURE.md |
| Commands become outdated | Cross-check against ARCHITECTURE.md before finalizing |

## Documentation / Operational Notes

- This is the documentation change. No other docs need updating.

## Sources & References

- Existing README: `README.md`
- Deep docs: `ARCHITECTURE.md`
- Code style: `CODE_STYLE.md`