Marketplace 2.0

Production-grade showcase repository for a modern web marketplace platform. Seven stages, each a focused, reviewable increment — no mystery code, no silently unfinished corners.

Stage	Focus	Status
1	Foundation and multi-service project structure	✅
2	Core backend with a working marketplace API	✅
3	Premium storefront connected to the backend API	✅
4	Search with Elasticsearch, analytics, recommendations	✅
5	Async workflows, Celery, Telegram notifications, audit	✅
6	Observability, security hardening, platform maturity	✅
7	Polish, a11y, demo readiness, docs	✅

Start here if you're new: ONBOARDING.md. Walk the product in 3 minutes: DEMO.md. Planning to ship it: DEPLOYMENT.md.

---

What is real end-to-end

• Auth — JWT access + refresh rotation, role-aware routes, revocation on logout.
• Catalog — Django + DRF + SQLAlchemy with Alembic migrations; 200-product demo seed covering 10 categories.
• Cart, promocodes, orders — real transactions, real stock decrement, real promo validation (POST /api/v1/promo/apply), SHA-256-chained admin audit.
• Async order progression — Celery + Redis walks PENDING_PAYMENT → PAID → … → DELIVERED; the order page polls every 3 seconds and renders the timeline from the status-history table.
• Search — Elasticsearch with bilingual (RU/EN) synonym expansion and automatic SQL fallback. Response metadata declares which backend answered so clients never misrepresent what happened.
• Telegram notifications — retried + deduplicated on status transitions; logs SKIPPED with a reason when the token is unset.
• Observability — /metrics (Prometheus), OpenTelemetry traces (Tempo), structured logs with correlation IDs end-to-end (HTTP → Celery → Notifications), pre-provisioned Grafana dashboard.
• Security — DRF throttles, security-header middleware on both API and storefront, CI scans (Bandit, pip-audit, npm audit, Trivy, Gitleaks), hardened .env.example.
• Frontend polish — App Router, Tailwind v4 design tokens, a11y skip link, labelled forms, route-level error boundaries, /ui-showcase component gallery, Russian metadata on every route.

What is intentionally a demo scaffold

These are honest about themselves in the code and in response metadata — they are not hidden or silently broken:

• Semantic search — deterministic embedding scaffold from Stage 4. Responses carry search.semantic.production_model: false.
• /payment/demo/<orderId> — SBP-style shell. No acquirer, no card fields. The "Демо оплата" button calls the mock payment endpoint.
• Product imagery — CSS gradients. No object storage / CDN yet.

What is deliberately out of scope

Explicitly not shipped, each with a reason in the stage notes they would have belonged to:

• Production image pipeline / CDN.
• Prometheus alert routing and on-call integration.
• Nonce-based CSP (static CSP is in place).
• HSTS preload (needs a production TLS story).
• Storybook (substituted by /ui-showcase; see docs/architecture/stage-7-polish-demo-readiness.md).

Repository layout

.
├── api/              Django + DRF + SQLAlchemy backend
│   ├── apps/         Django apps (auth, config wiring)
│   ├── marketplace/  Domain packages (catalog, orders, cart, …)
│   ├── tests/        Pytest integration suites
│   └── alembic/      Business-schema migrations
├── frontend/         Next.js App Router storefront
│   ├── src/app/      Routes + metadata + error boundaries
│   ├── src/features/ Feature slices (auth, cart, catalog, …)
│   ├── src/widgets/  Composite UI blocks
│   ├── src/shared/   Primitives, lib, API client
│   └── e2e/          Playwright smoke + flow tests
├── infra/
│   ├── compose/      Local compose topology + overlays
│   ├── helm/marketplace/  Helm chart scaffold
│   └── k8s/base/     Kubernetes base scaffold
├── worker/           Async contour bootstrap
├── docs/             Architecture notes, runbooks, stage docs
├── DEMO.md           Demo walkthrough
├── DEPLOYMENT.md     Production deployment guidance
├── ONBOARDING.md     Developer onboarding
├── Makefile
└── package.json

Local bootstrap

Prerequisites

• Node.js 22+
• Python 3.12
• Docker + Docker Compose

Install and run

make bootstrap                      # installs root, frontend, api
cp .env.example .env
make api-migrate                    # Alembic migrations
docker compose -f infra/compose/docker-compose.yml up -d --build
make compose-smoke

Or, with the observability stack (Prometheus, Grafana, Loki, Tempo, Alloy):

make obs-up

Default endpoints

Surface	URL	Notes
Storefront	http://localhost:3000	—
API docs	http://localhost:8000/api/docs	Swagger UI
OpenAPI JSON	http://localhost:8000/api/openapi.json	—
API liveness	http://localhost:8000/api/v1/health/live	LB-friendly
FE liveness	http://localhost:3000/api/health/live	LB-friendly
Grafana	http://localhost:3001	admin / admin (dev only)
Prometheus	internal to compose network	Not publicly bound in prod
Elasticsearch	http://localhost:9200/\_cluster/health	—

Demo accounts (seeded)

• user@mayss.demo / User1234! — has one pre-seeded DELIVERED order.
• admin@mayss.demo / Admin1234!

See DEMO.md for the walkthrough.

Configuration templates

• .env.example — root compose variables.
• api/.env.example — backend.
• frontend/.env.example — frontend.
• worker/.env.example — worker.

Backend API groups

• Auth — POST /api/v1/auth/register, /login, /refresh, /logout
• Profile — GET /api/v1/profile, PATCH /api/v1/profile
• Catalog — GET /api/v1/categories; GET/POST /api/v1/products; GET/PATCH/DELETE /api/v1/products/{id-or-slug}
• Cart — GET /api/v1/cart; POST /api/v1/cart/items; PATCH/DELETE /api/v1/cart/items/{id}
• Promo — POST /api/v1/promo/apply
• Orders — GET/POST /api/v1/orders; GET /api/v1/orders/{id}; GET /api/v1/orders/{id}/history; POST /api/v1/orders/{id}/pay
• Search — GET /api/v1/search/products?q=charge; POST /api/v1/search/reindex; POST /api/v1/search/reindex/{product_id}
• Recommendations — GET /api/v1/recommendations/popular; GET /api/v1/recommendations/products; POST /api/v1/recommendations/events
• Admin — GET /api/v1/admin/stats; POST /api/v1/admin/assign-admin; GET /api/v1/admin/audit; GET /api/v1/admin/audit-chain/status

Frontend routes

• / — homepage with API-backed product shelf
• /catalog — URL-driven filters, sorting, pagination, search
• /products/[productId] — product details with attributes + cart CTA
• /cart — authenticated cart with quantity + promo
• /checkout — validated checkout + handoff to demo payment
• /payment/demo/[orderId] — SBP-style demo payment
• /login, /register, /profile, /orders/[orderId]
• /ui-showcase — design-system gallery (noindex)

Quality gates

The repository is wired with:

• Prettier for repo-wide formatting.
• ESLint + TypeScript for the frontend.
• Ruff + Django checks for the backend.
• Pytest integration coverage for backend scenarios.
• Vitest coverage for frontend helpers, metadata, and API client.
• Playwright Chromium e2e — smoke + orders + profile + logout + catalog filter flows, hermetic against a mocked API.
• Docker image build verification for API and frontend.
• GitHub Actions workflow in .github/workflows/ci.yml.
• Security scans: Bandit (SAST), pip-audit, npm audit, Trivy, Gitleaks.
• /metrics smoke test on every CI run.

Run it all locally:

make format-check
make lint
make typecheck
make test
cd frontend && npm run test:e2e -- --project=chromium
make compose-config
make build
make security-scan

Documentation map

• ONBOARDING.md — developer onboarding.
• DEMO.md — demo walkthrough.
• DEPLOYMENT.md — production deployment notes.
• docs/architecture/stage-1-foundation.md — Stage 1.
• docs/architecture/stage-2-core-backend.md — Stage 2.
• docs/architecture/stage-3-frontend-storefront.md — Stage 3.
• docs/architecture/stage-4-search-ml.md — Stage 4.
• docs/architecture/stage-5-async-audit.md — Stage 5.
• docs/architecture/stage-6-observability-security.md — Stage 6.
• docs/architecture/stage-7-polish-demo-readiness.md — Stage 7.
• docs/architecture/adr-0001-foundation-bootstrap.md — foundation ADR.
• docs/observability.md — telemetry stack.
• docs/security.md — security posture.
• docs/local-development.md — local workflow.
• docs/runbooks/metrics-and-alerting.md
• docs/runbooks/incident-response.md
• docs/stage-7-audit.md — Stage 7 audit and priority list.