Project README, CONTRIBUTING and dev setup

[AlexTuring010]

Background / Context

The repository root README.md is currently a single line (# AllHackathons), so a new contributor has no idea what the project is or how to run it. The two runnable pieces are the React 19 + Vite + TypeScript frontend in frontend/ (scripts in frontend/package.json: dev, build, preview; bun.lock is the committed lockfile) and a Flask stub backend in backend/ (backend/main.py, currently only /health and /ping, documented in backend/README.md). There is no top-level CONTRIBUTING.md and no single place that points contributors at the canonical data model and /api REST contract that other issues build against.

This is documentation only — it does not change any application code. It lands early (Wave 0, no dependencies) because it unblocks everyone else.

Goal

Replace the placeholder README.md with a real project README and add a CONTRIBUTING.md, so that someone who has never seen the repo can clone it, run both the frontend and backend, understand the project layout, and know how to pick up an issue and open a PR.

Tasks

Root README.md

• One-paragraph description: AllHackathons is a website that lists hackathons, and anyone visiting can submit one.
• Tech stack section: frontend = React 19 + Vite + TypeScript + Tailwind v4 + shadcn/ui + react-router-dom; backend = Flask (Python). Note the backend is currently a stub (backend/main.py exposes only /health and /ping).
• Current state note: data is presently sourced from frontend/src/lib/sample-hackathons.ts merged with localStorage; there is no live API yet. Link out (by title) to the relevant open issues — "Expanded Hackathon data model & REST API contract", "Backend REST API for hackathons (Flask)", and "Frontend: wire UI to the API" — so readers know this is in flight.
• Run the frontend section: cd frontend, install deps (bun install, or npm install), then bun run dev / npm run dev (Vite dev server). Mention bun run build and bun run preview. Copy the exact script names from frontend/package.json (dev, build, preview) — do not document scripts that are not in that file.
• Run the backend section: cd backend, pip install -r requirements.txt, then run the dev server exactly as backend/README.md documents (mirror its command and port verbatim rather than guessing). Recommend a virtualenv (the .gitignore already ignores env).
• Project structure section: a short tree describing frontend/src/pages/ (Home.tsx, Feedback.tsx), frontend/src/components/ (SubmitHackathonModal.tsx, HackathonCard.tsx, Header.tsx, plus components/ui/ shadcn primitives), frontend/src/lib/ (types.ts, sample-hackathons.ts, utils.ts), frontend/src/App.tsx (router), and backend/main.py.
• Data model & API contract section: state that the canonical Hackathon data model and the /api REST contract live in the "Expanded Hackathon data model & REST API contract" issue (link it by title), so frontend and backend stay aligned. Note that the live Hackathon type today is in frontend/src/lib/types.ts and still uses the thin/legacy field names (topic, date, prize, link) pending the expanded model (name, startDate/endDate, hasPrize, url). Mention that endpoint ownership (which issue implements each /api path) is declared in that same contract issue, so contributors do not duplicate server-side work.
• Contributing section: short pointer to CONTRIBUTING.md.

CONTRIBUTING.md (repo root)

• Picking up an issue: comment to claim it, check the issue's depends on first, keep PRs small and scoped to one issue.
• Branch naming: a simple convention, e.g. feature/<short-desc>, fix/<short-desc>, docs/<short-desc>.
• Pull requests: open a PR against the default branch, reference the issue it closes (Closes #NN), describe what changed, request review.
• Code style: frontend is TypeScript + React function components, styled with Tailwind utility classes and shadcn/ui (frontend/src/components/ui/); backend is Python/Flask. New code should match the surrounding files; run bun run build before opening a frontend PR to catch type errors.
• Contract alignment: remind contributors to use the canonical field names (name, url, startDate, endDate, hasPrize, mode, etc.), the four status values (draft | pending | published | needs-changes), the mode union (in-person | online | hybrid), the name-OR-url submission rule (only one of name/url is required), the /api base path, ISO 8601 dates, and the { error: string } error shape from the data-model/API-contract issue — do not invent alternative names or paths.

Acceptance criteria

• Root README.md describes what AllHackathons is and lists the stack.
• Following the README, a contributor can start the frontend (cd frontend → install → dev) and the backend (cd backend → pip install -r requirements.txt → the dev command/port copied from backend/README.md) without further guesswork.
• README contains a project-structure overview referencing real paths under frontend/src/ and backend/.
• README points to where the canonical data model and /api contract live, and notes that endpoint ownership is declared there.
• CONTRIBUTING.md exists at the repo root and explains how to claim an issue, the branch/PR conventions, code style, and the contract-alignment reminder (canonical field names, the four status values, and /api/... paths).
• Both files are committed and render correctly in GitHub-flavored Markdown (no broken headings or code fences).

Dependencies

None. This issue intentionally has no dependencies (Wave 0) so it can land first and unblock other contributors. It should link out to the "Expanded Hackathon data model & REST API contract", "Backend REST API for hackathons (Flask)", and "Frontend: wire UI to the API" issues by title once they exist, but does not block on them.

Out of scope / notes

• No application code changes — documentation files only. Do not modify frontend/src/lib/types.ts, backend/main.py, or any component; the model migration (topic→name, date→startDate/endDate, prize→hasPrize, link→url, etc.) happens in the data-model issue.
• No CI config, linter setup, or CODE_OF_CONDUCT.md — keep this realistic for a small volunteer student team; those can be follow-ups.
• Keep commands accurate to what is actually committed: only bun.lock is present (npm also works with the standard scripts), and frontend/package.json exposes dev/build/preview only. Before posting/committing, open frontend/package.json and backend/README.md and confirm the documented scripts, backend dev command, and port match those files exactly — do not hardcode anything that might drift.
• An on-site admin review UI for pending / needs-changes items is a known follow-up not yet drafted; the README/CONTRIBUTING do not need to document it, but do not claim contributors can action pending submissions on the site today.
• Labels: only existing repo labels are applied (documentation, good first issue). A dedicated docs epic label is unnecessary — documentation already fits. Maintainers may separately want to create backend, frontend, and design labels, which nearly every implementation issue references in prose.