Skip to content

GL-339: Rewrite docs/architecture.md + reconcile 'no raw SQL' doctrine + repo hygiene #45

Description

@discodone

Review source

Round 14 (Gemini + Opus 4.8) — P2/P3, dangerously misleading docs.

Problem

  1. docs/architecture.md is completely out of date — it describes a simple Python script, not the layered FastAPI application that exists. A new developer would be completely lost.
  2. CLAUDE.md states 'No raw SQL anywhere' yet raw SQL with ?/text() placeholders lives in auth/auth.py (workspace resolver), api_keys.py, exports.py, challenges.py, health.py. The architecture doc contradicts reality.
  3. Repo hygiene: stray '=0.19.0' file (a pip install redirection artifact), coverage.json, scripts/output.log, logs/ are all uncommitted clutter in the tree.
  4. License inconsistency: README.md states 'Apache License 2.0' while the license badge points to MIT.

Fix

  • Rewrite docs/architecture.md from scratch: FastAPI, Routers, Services, Repositories, arq workers, SQLAlchemy, multi-tenancy model. Use a request-flow diagram through the layers.
  • Reconcile the 'no raw SQL' claim: either remove the absolute claim from CLAUDE.md and document where/why raw SQL is used (with parameterization safety notes), or migrate the remaining raw SQL to ORM
  • Clean repo: rm the '=0.19.0' artifact, add coverage.json, scripts/output.log, logs/ to .gitignore
  • Fix license inconsistency: align README, badge, and LICENSE file

Acceptance Criteria

  • architecture.md accurately reflects the current layered design
  • CLAUDE.md no longer contradicts reality re: raw SQL
  • .gitignore covers all build/log artifacts; junk files removed
  • License is consistent across README, badge, LICENSE
  • mypy clean, ruff clean, tests >= baseline

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions