{"id":46371238,"url":"https://github.com/onlydole/overdue","last_synced_at":"2026-03-05T04:01:24.284Z","repository":{"id":339687370,"uuid":"1162992500","full_name":"onlydole/overdue","owner":"onlydole","description":"Don't let your knowledge expire. A FastAPI-powered knowledge library game.","archived":false,"fork":false,"pushed_at":"2026-02-21T01:31:32.000Z","size":126,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-21T06:15:04.498Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onlydole.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-21T00:05:23.000Z","updated_at":"2026-02-21T01:31:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/onlydole/overdue","commit_stats":null,"previous_names":["onlydole/overdue"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/onlydole/overdue","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onlydole%2Foverdue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onlydole%2Foverdue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onlydole%2Foverdue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onlydole%2Foverdue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onlydole","download_url":"https://codeload.github.com/onlydole/overdue/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onlydole%2Foverdue/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30109075,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T03:40:26.266Z","status":"ssl_error","status_checked_at":"2026-03-05T03:39:15.902Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-05T04:00:47.702Z","updated_at":"2026-03-05T04:01:24.260Z","avatar_url":"https://github.com/onlydole.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Overdue\n\n\u003e Your knowledge is fading. Fight back.\n\n[![Ask Dosu](https://img.shields.io/badge/Ask%20Dosu-our%20archivist-f0c543?style=flat\u0026labelColor=0f0e17)](https://app.dosu.dev/04283041-db40-47f2-9553-9b7452d3ac02/ask)\n\nOverdue is a gamified knowledge library where every fact you capture starts decaying the moment you shelve it. You're a **librarian** in a pixel art world -- shelving **volumes** of knowledge, watching their **Dewey Scores** crumble as dust settles, and racing to review them before they're lost. Earn XP (\"pages read\"), climb ranks from Page to Head Librarian, unlock badges, and keep your streak alive. Neglect your stacks and the Reading Room descends into chaos.\n\nThis isn't a to-do app with a theme. It's a game that happens to make you smarter.\n\n## What Makes It Tick\n\n- **Dewey Score decay** -- Every volume starts at 100 and rots toward 0. Review it to reset the clock. Ignore it and watch it crumble.\n- **XP and ranks** -- Earn pages read for every action. Rise from Page (0 XP) through Shelver, Librarian, and Archivist to Head Librarian (5,000 XP).\n- **11 badges across two tiers** -- From \"First Shelve\" (Common) to \"Marathon Reader\" (Rare, 30-day streak). Collect them all for the Completionist badge.\n- **Streaks** -- Review daily for +15 bonus pages. Miss a day and your streak resets. The pressure is real.\n- **Reading Room mood** -- The library's ambient atmosphere shifts from \"Quiet Study\" (golden glow) to \"Closed for Renovation\" (crisis mode) based on your collective Dewey Scores.\n- **AI bot players** -- Casual, diligent, and obsessive bots populate the leaderboard and keep things competitive while you sleep.\n- **Pixel art everything** -- 26 hand-crafted SVG icons, 8 heroic librarian avatars, custom dark parchment palette. Zero emoji.\n- **Keyboard shortcuts** -- `Enter` to review, arrows to navigate, `Escape` to go back. Fly through your stacks.\n\n## Quick Start\n\n```bash\ngit clone https://github.com/onlydole/overdue.git\ncd overdue\ndocker compose up --build\n```\n\nOpen `http://localhost:8000`, register your first librarian, and start shelving.\n\nThe database, demo data, and bot players are all set up automatically. Manage the library with Docker Compose:\n\n```bash\ndocker compose exec overdue overdue bots simulate    # Shuffle the leaderboard\ndocker compose exec overdue overdue stats             # Library statistics\ndocker compose exec overdue overdue seed demo         # Re-seed demo data\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eRunning without Docker\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/onlydole/overdue.git\ncd overdue\npython -m venv .venv\nsource .venv/bin/activate  # Windows: .venv\\Scripts\\activate\npip install -e \".[dev]\"\nuvicorn src.main:app --reload\n```\n\n\u003c/details\u003e\n\n## The Stack\n\n| Layer | Tech |\n|---|---|\n| Backend | FastAPI (Python 3.12+), fully async |\n| Frontend | Jinja2 + HTMX, Alpine.js for small UI state |\n| Styling | Tailwind CSS with custom dark parchment palette |\n| Database | SQLAlchemy async + aiosqlite (SQLite default) |\n| Auth | PyJWT (HS256) with HMAC-safe key derivation |\n| CLI | Typer with subcommands for everything |\n| Deployment | Docker (Python 3.12-slim), non-root, healthcheck |\n\n## API Quick Reference\n\n| Endpoint | What It Does |\n|---|---|\n| `POST /api/librarians/register` | Get your library card |\n| `POST /api/librarians/login` | Flash your credentials |\n| `POST /api/volumes/` | Shelve new knowledge |\n| `POST /api/volumes/{id}/review` | Brush off the dust |\n| `GET /api/reading-room/health` | Check the library's mood |\n| `GET /api/librarians/leaderboard` | See who's on top |\n\nFull reference: [docs/api/endpoints.md](docs/api/endpoints.md)\n\n## Configuration\n\nAll settings use the `OVERDUE_` prefix. Key variables:\n\n| Variable | Default | What It Controls |\n|---|---|---|\n| `OVERDUE_SECRET_KEY` | insecure default | JWT signing -- **change in production** |\n| `OVERDUE_DATABASE_URL` | `sqlite+aiosqlite:///./overdue.db` | Where your library lives |\n| `OVERDUE_DEWEY_DECAY_SECONDS` | `10` | How fast dust settles (86400 for daily) |\n| `OVERDUE_STREAK_COOLDOWN_SECONDS` | `5` | Seconds between streak-eligible reviews |\n| `OVERDUE_PORT` | `8000` | Server port |\n| `OVERDUE_ALLOWED_ORIGINS` | `[\"*\"]` | CORS allowlist |\n\nFull list: [docs/guides/configuration.md](docs/guides/configuration.md)\n\n## Development\n\n```bash\npytest                          # Run the test suite\nruff check src/ tests/          # Lint\nruff format src/ tests/         # Format\nnpm run css:build               # Rebuild Tailwind CSS\npython scripts/build_icons.py   # Regenerate pixel art SVGs\n```\n\n## Project Structure\n\n```text\nsrc/\n  api/          # REST endpoints (volumes, shelves, catalog, reading room, bulletins)\n  auth/         # JWT library cards, session cookies, role-based access\n  cli/          # Typer CLI (serve, seed, auth, stats, bots, shelves, volumes)\n  config/       # Pydantic Settings, game balance constants, rate limiting\n  db/           # Async engine, ORM tables, demo seed data\n  errors/       # Library-themed exceptions and handlers\n  game/         # XP engine, badges, streaks, mood, bots, pixel art icons \u0026 avatars\n  models/       # Pydantic schemas and SQLAlchemy models\n  web/          # HTML routes, Jinja2 template config, mood middleware\ntemplates/      # Jinja2 templates and partials\nstatic/         # CSS, JS, pre-rendered SVG pixel art\ntests/          # pytest suite\ndocs/           # Guides, API reference, architecture, changelog\n```\n\n## Documentation\n\n- [Installation](docs/guides/installation.md)\n- [Quick Start](docs/guides/quickstart.md)\n- [Configuration](docs/guides/configuration.md)\n- [Gameplay Guide](docs/guides/gameplay.md) -- XP, ranks, badges, streaks, mood\n- [Bot Players](docs/guides/bots.md) -- AI competition\n- [API Endpoints](docs/api/endpoints.md)\n- [Authentication](docs/api/authentication.md)\n- [Architecture](docs/architecture/overview.md)\n- [Changelog](CHANGELOG.md)\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonlydole%2Foverdue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonlydole%2Foverdue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonlydole%2Foverdue/lists"}