Shadowline Hackathon Workspace

This workspace collects everything you need to understand, run, and extend the Shadowline Legal Router hackathon project. Use this guide to jump to the right docs, code, or helper scripts without digging through directories.

Where to Start

1. Read artifacts/requirements.md for the product scope and legal framing.
2. Skim artifacts/architecture.md and artifacts/plan.md for system design and delivery plan.
3. Move into project/README.md for build/run/setup instructions covering the full stack.

Directory Map

• artifacts/ – Planning deliverables and research support.
  • architecture.md – System blueprint and architectural drivers.
  • plan.md – Iteration roadmap with task breakdowns.
  • requirements.md – Product requirements and legal references.
  • todo.json – Structured backlog items.
  • lints/ – Historical lint/test outputs grouped by iteration/task.
• project/ – Application source code and operational tooling.
  • backend/ – FastAPI service, Celery workers, Alembic migrations, and API tests.
  • frontend/ – React + TypeScript client, Tailwind config, and UI tests.
  • api/ – OpenAPI specification (spec.yaml) with supporting notes.
  • docs/ – ADRs and PlantUML diagrams that back the architecture.
  • tools/ – Helper scripts (install.sh, lint.sh, run.sh, test.sh) for local workflows.
  • docker-compose.yml – Spins up the entire stack (Postgres, Redis, backend, frontend, workers).
• tickets/ – Placeholder for work tickets or issue exports (currently empty but reserved for triage).

Typical Tasks

• Boot the stack: From project/, run docker compose up --build (details in project/README.md).
• Backend development: Activate the virtualenv in project/backend/, run uvicorn app.main:app --reload, and use pytest for tests.
• Frontend development: Install dependencies and start the dev server via npm install && npm start in project/frontend/.
• Docs and diagrams: project/docs/ contains ADRs plus PlantUML sources in diagrams/.
• Automation scripts: Execute the bash helpers from project/tools/ to install deps, lint, or test both services.

Tips

• Keep the artifacts/ folder up to date when new architectural decisions are made.
• Add new project automation to project/tools/ so teammates get consistent entry points.
• Place future work items or imported issues into tickets/ to keep planning artifacts separate from code.