From f3be99e4e2ff1233878f8ff8a031d554bebcc34e Mon Sep 17 00:00:00 2001 From: Zareian Date: Mon, 14 Sep 2026 02:44:03 +0330 Subject: [PATCH] record where this project is heading, not just how it works MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit هر ایجنتِ تازه ساختارِ کد را می‌بیند ولی نمی‌داند صاحبِ پروژه دنبالِ چیست: دو ریپو و یک قراردادِ API (نه ادغامِ ریپوها)، حذفِ هر قدمِ دستی از انتشار، محتوای قابلِ ویرایش بدونِ برنامه‌نویس، و سنجش‌پذیر بودنِ کیفیتِ پاسخِ AI. بدونِ این، پیشنهادها به سمتی می‌روند که با مسیرِ پروژه نمی‌خواند. Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 3479e52..7155f30 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -64,6 +64,34 @@ API docs: Swagger `/api/docs/`, Redoc `/api/redoc/`, admin `/admin/`. **Payment (Zarinpal)**: `create_order`/`CreateOrderView` never call Zarinpal directly — `paymentUrl` points at our own `GET /api/payment/orders/{id}/pay` (`PaymentRedirectView`), which calls Zarinpal's PaymentRequest API on first visit (storing `Order.gateway_authority`) and redirects to StartPay; this keeps order creation from depending on Zarinpal's uptime. Zarinpal redirects the user back to `GET /api/payment/zarinpal/callback` (`ZarinpalCallbackView`), which always re-verifies server-to-server via `payment/zarinpal.py::verify_payment` before marking an order paid — a forged `Status=OK` in the query string alone does nothing. Both `payment/zarinpal.py` and `payment/bazaar.py` fail closed (503 / invalid) when their credentials aren't configured, never a fake success. +## Where this is heading (the owner's intent) + +The owner writes this backend; another developer writes the frontend; a third person +administers the server. None of them share a machine, and until recently the two halves +were built in parallel without a shared contract — which is why reconciling them cost +rework. The goal is not to merge the repos. **Two repos, one API contract** is the +intended shape, and the contract lives in this repo's OpenAPI schema (`/api/docs/`), not +in anyone's head. + +What the owner is steering toward, in rough order: + +1. **Both halves running against each other**, on real content, with nobody hand-editing + files on the server. Most of the plumbing for this now exists. +2. **Nothing manual in a release.** Adding a dependency, a setting or a service must not + add a step someone has to remember. When a change would, fold it into `deploy.sh` or + make startup fail loudly and legibly instead. +3. **Content editable without a developer** — questions, curriculum, plan copy, all from + the admin panel. A management command run over SSH is a last resort, not a workflow. +4. **Answer quality measurable**, not assumed: per-question reports, wrong-answer rates, + prompt-version feedback. The senior's stated priority is proving the AI actually + teaches, especially where students get stuck. +5. **Scale without drama** — thousands of concurrent users should be a non-event. Prefer + the boring fix (an index, a cache, a cheap guard) over new infrastructure. + +The owner is early in their career and learning the collaboration workflow as they go. +Explain the *why* alongside the *what*, flag when something is a product decision rather +than a coding one, and never assume a step was done just because it was described. + ## Frontend ↔ backend (read before wiring the two together) The app is two repos and two domains: the React frontend lives in