Skip to content

Wiki is nine months out of date with the shipped system #1

Description

@PhilippTheServer

The wiki was last updated on 2025-12-07. Since then the API grew from a single item-store
service to eleven service modules (customers, orders, payments, inventory, fulfillment,
shipments, returns, webhooks, admin, health), gained a background worker, a transactional
outbox, MinIO object storage and a Stripe integration — and a storefront frontend landed
today in OpenTaberna/frontend.

None of that is in the wiki, and several pages actively mislead:

  • home.md names MySQL for storage; the system runs PostgreSQL 17.
  • home.md diagrams an Elasticsearch / Logstash / Kibana stack and an Nginx reverse proxy
    that exist in no compose file.
  • Database/Architecture.md documents shops, categories, item_categories,
    item_media, attributes, item_attributes and item_events — none of these tables
    exist
    . The real schema is 12 tables and the item detail is held in JSONB columns.
  • Getting-Started.md clones PhilippTheServer/opentaberna, a repository layout that does
    not exist; the project is four repositories.
  • Getting-Started.md documents endpoints under /api/v1/...; the real prefix is /v1/....
  • Getting-Started.md claims GET /health returns {"status":"healthy","version":"0.1.0"}
    and that GET / returns the API version. The real health payload is
    {"status":"ok","timestamp":...} and GET / is a 404.
  • Nothing documents the authorization model (the admin role plus the azp client check),
    the order/payment/return/shipment state machines, or the storefront.

Expected once solved

The wiki describes the system that is actually running:

  1. Every endpoint the API serves is documented, and every documented endpoint exists.
  2. The schema page lists the tables that are really in the database.
  3. Setup instructions work against the four real repositories and the real ports.
  4. The authorization model and order lifecycle are documented.
  5. An automated check fails when the wiki drifts from the API again.

Activity

  1. PhilippTheServer commented on Aug 26, 2026

    @PhilippTheServer
    ContributorAuthor

    Solved in #2 (squash-merged as 8e224db).

    Every page was rewritten against a running instance of the current stack rather than from
    memory: the endpoint list came from /openapi.json, the schema from \d against the live
    PostgreSQL container, config defaults from settings.py, and the token flow was exercised
    end to end (adminuser → 200 on /v1/admin/orders/, no token → 403).

    The specific falsehoods this issue listed are gone: PostgreSQL replaces MySQL, the ELK
    stack and phantom gateway are removed, the seven tables that never existed are replaced by
    the twelve that do, the repository layout and /v1 prefix are correct, and the documented
    health payloads match what the API returns.

    Two pages were added for subsystems the wiki had never covered — Authorization.md and
    Orders-and-Fulfillment.md.

    The old normalised schema is kept on the database page under "The road not taken",
    explicitly labelled a proposal with the trade-off it was rejected for. It was a proposal
    being read as a description that caused most of the damage here.

    The regression check: tools/check_wiki.py fails when the API serves an endpoint no
    page mentions, when a page documents a path the API does not serve, or when an internal
    link dangles. Against the old content it reported 27 failures; against the merged content
    it passes. CI runs it on every push and PR.

    It reads a committed openapi.snapshot.json so CI needs nothing running — which also means
    refreshing that snapshot after an API change is what makes the check bite, and that step is
    documented in the README.

    One loose end left deliberately: Database/database_diagram_layout.jpg is now unreferenced,
    since it pictures the schema that was never built. It was left in place rather than deleted
    unasked.

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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions