Features¶
This lists what the code actually implements today, and — just as importantly — what is gated on configuration. The backend is feature-complete for its route surface; several money- and identity-touching paths deliberately return errors until their external provider is configured, rather than pretending to work.
Terminology: "gated" = the code path exists but refuses to operate until a credential/config is present; it fails closed, never open.
Backend (aim-backend)¶
Live, dual-auth REST API under /api/v1. Full endpoint list in the
API Reference. Working capability groups:
- Auth — password register/login, SMS OTP login (auto-creates user +
wallet), token refresh, server-side logout/revocation, admin password
login (
POST /auth/admin/login, rate-limited, uniform 401), OTP email verification (/me/email/send-otp+verify-otp, see the gate below), and an optional reviewer login — a fixed OTP for exactly one configured number (REVIEWER_LOGIN_PHONE/REVIEWER_LOGIN_OTP) so payment-gateway and app-store reviewers can sign in without our SMS; only delivery changes, every gate and limit still applies, and admin accounts are excluded. - Referrals — per-user share codes (
GET /referrals/my-code), the public/r/:codeclick-logging Play Store redirect, and attribution-only signup tracking (users.referred_by+referral_attributions; explicit code first, IP-match fallback). No wallet rewards — see ADR 0012. - Storefront — public products/categories, server-authoritative quote →
order → cancel, paid from the shopping-credits wallet. Products carry an
ordered image gallery alongside the single cover image — see ADR
0013. Catalogue images are either
uploaded (
POST /api/v1/admin/uploads/image, stored content-addressed and served atGET /media/:key) or referenced by URL. - Wallet — balance, transactions, claims, daily spin, and the verified top-up flow (see the gate below).
- Fantasy — Entity Sport sync, contests + templates, teams, live scoring, Redis leaderboards, finalize/void with wallet payouts, pick-one-player sets.
- Predictions — admin-synced markets plus the user-facing orderbook (place/cancel orders, book, activity, positions).
- Account deletion — Google-Play-compliant: an unauthenticated OTP-proven web flow and an authenticated in-app flow with eligibility, status, and cancel.
- Support desk — see ADR
0016. A public Help Centre
(
GET /support/help: admin-configured topics and FAQs, hiding topics whose feature toggle is off). Signed-in customers raise tickets, optionally about an order, then reply, confirm or reopen the resolution, rate it, and escalate to the Grievance Officer, which starts a statutory deadline (the earlier of 30 days and one month) that never pauses. Agents get a queue with per-priority SLA state, assignment, internal notes, canned replies, a resolution form, a dashboard and an email log. An active grievance past that statutory deadline is counted on its own (dashboard tile, queue filtersla=grievance_overdue, criticalSupportGrievanceBreachedalert); a grievance that only misses its internal SLA target counts as an ordinary SLA breach. Agents work in the support portal (support.aimstoreorg.com, ADR 0018) — a Support role that cannot open the admin portal; topics, FAQs, templates, resolution codes, settings and the email log are edited in the admin portal. Emails go through a transactional outbox and a background worker, and only ever to a verified address. Support never moves money: refunds and cancellations stay on their own flows. - Affiliates — application, KYC upload, stats/earnings, click tracking, admin approval + payouts.
- Admin — the whole
/api/v1/admin/*back office (fantasy ops, catalogue + catalogue-image uploads, gateways, users, orders/refunds/reconciliation, tickets, affiliates, predictions, Entity proxy). - Observability —
/health, Prometheus/metrics(fiberprometheus), OTLP-HTTP traces (otelfiber) whenOTEL_EXPORTER_OTLP_ENDPOINTis set.
What is gated, and on what¶
| Capability | Gate | Behaviour until configured |
|---|---|---|
| Website checkout / top-up pages | CCAVENUE_* + PHONEPE_* on the payment server |
payment endpoints return 503; storefront browsing still works (server/index.js logs a warning at boot) |
| Backend top-up initiate | TOPUP_PAGE_BASE_URL |
POST /wallet/topup-initiate returns 503 — it never routes users to an unconfigured/retired merchant page |
| Backend top-up credit callback | STORE_WEBHOOK_SECRET |
POST /wallet/topup-credit returns 503 ("callback verification not configured") — credits are impossible without HMAC verification |
| Top-up status self-heal | PHONEPE_CLIENT_ID/SECRET |
GET /wallet/topup-status/:token can't verify with PhonePe and leaves the top-up pending |
| OTP login | SMS provider (SMS_* vars, alots.in gateway in pkg/sms) |
OTP send fails with a generic error and the stored OTP is deleted; password auth still works |
| Fantasy + predictions (whole process) | ENTITY_ACCESS_TOKEN |
the backend exits at boot (mustGetEnv in config/config.go) — this is a hard requirement, not a soft feature flag |
| Firebase bearer auth | FIREBASE_SERVICE_ACCOUNT_PATH |
only the custom-JWT header works |
| Support-desk emails | SMTP_* |
the support desk works end to end in the app, website and portal; each email is queued, never sent, and marked dead after the email_max_age_hours setting (72h), so enabling SMTP later does not mail a stale backlog. The SupportMailerUnavailable alert and a portal banner show the state. Customer emails also need a verified address (else skipped) |
| Support worker | SUPPORT_WORKER_ENABLED (default true) |
when false: no support email is sent, resolved tickets never auto-close, no reminders or auto-resolve, and the aim_support_* gauges stop updating, so the SLA and grievance-deadline alerts cannot fire (the portal's Support dashboard still shows breaches). Tickets themselves keep working |
| Help Centre topics for gated features | feature_toggles rows (e_vouchers, gift_cards, spin_win, karat24) |
a topic whose toggle is off is hidden from /support/help and cannot be chosen for a new ticket; a missing toggle row counts as on, except karat24, which needs an explicit true |
| Email verification | SMTP_* |
POST /me/email/send-otp returns 503 {"error":"email_disabled"}; accounts simply stay unverified (email_verified: false) |
| Referral attribution | nothing — always on | n/a: share links, click logging, and signup attribution need no external provider (share hosts come from PLAY_STORE_URL / REFERRAL_SHARE_BASE_URL, which have working defaults) |
| Traces | OTEL_EXPORTER_OTLP_ENDPOINT |
no traces exported; metrics/logs unaffected |
Wallet top-up is gateway-verified only — by design
The legacy POST /wallet/topup route credited shopping_credits with no
payment, so any logged-in user could mint store currency. The route is
intentionally unrouted in routes.go (the handler survives only
because the verified gateway callbacks reuse the repo method). Money
enters exclusively via topup-initiate → hosted gateway page → verified
topup-credit / topup-status. Do not re-add the direct route.
Website (aim-store-website)¶
React 19 + Vite SPA at aimstoreorg.com, with an Express server
(server/index.js, :3001) that serves the built SPA in production and
fronts the payment gateways:
- Storefront — catalogue, search, wishlist, cart, checkout, policies (refund/return/shipping/terms), account deletion page. Product pages show the full image gallery (arrows, thumbnails, arrow-key navigation).
- Support — the FAQ page (also at
/help) renders the backend Help Centre, falling back to its built-in FAQ when the API is unreachable. For a signed-in customer the contact page raises a real ticket; signed-out visitors keep themailto:form. "My support requests" (/support/tickets) lists tickets with an unread count and shows each thread with reply, confirm, reopen, rate and escalate. - Payment plumbing — CCAvenue encrypt/redirect + response handling,
PhonePe OAuth + checkout + webhook, and the wallet top-up variants of
both, which call the backend's HMAC-verified
topup-credit. Deep-links back into the app via theaimstorescheme. GET /api/healthreports{status, payments}so you can see the gate state at a glance.
Mobile app (aim-store-app)¶
Expo SDK 57 / React Native app (expo-router): OTP sign-in, storefront (home, categories, product pages with a swipeable image gallery, cart, checkout), orders + order status, wallet credits + transactions + top-up (via the website's hosted page), rewards/daily spin, gift cards & e-vouchers screens, saved addresses, a Help Centre with support requests (raise, follow, reply, confirm or reopen, rate, escalate to the Grievance Officer; unread badge on Profile), legal pages, and the full Google-Play account-deletion flow. Env files select dev/staging/prod hosts; release builds refuse localhost/HTTP values.
Admin portal (aim-store-admin)¶
Next.js 14 App Router portal at admin.aimstoreorg.com, port 3002.
NextAuth credentials login against the backend's
POST /api/v1/auth/admin/login; the browser never holds the API token —
server-side routes proxy requests and inject x-sdk-access-token.
Operational pages map onto the /api/v1/admin/* modules (dashboard, users,
orders/refunds, products, gateways, fantasy ops, tickets, affiliates,
predictions), plus a link out to Grafana (NEXT_PUBLIC_MONITORING_URL). The
Support group holds the desk's configuration — Topics & FAQs, Templates, an
Email log and Settings (ADR 0016)
— and links out to the support portal. Users → Edit sets a user's Role
(Customer, Support agent or Admin; changing it needs a Super Admin).
Support portal (aim-store-support/)¶
Next.js 14 App Router portal at support.aimstoreorg.com, port 3004 (ADR
0018). The support
dashboard and the ticket queue / detail pages moved here from the admin
portal, whose old /tickets/* and /support/dashboard URLs redirect here.
NextAuth credentials login against POST /api/v1/auth/support/login, which
admits Support-role users and admins. Same server-side proxy pattern as the
admin portal, but it forwards only /api/v1/support-desk/* (gated by
SupportStaffOnly), so the portal cannot reach the admin API whoever is
signed in.
Deploy & CI/CD (deploy/, .github/workflows/)¶
Push to main → GitHub Actions build → GHCR → SSH pull-deploy to the VPS,
with pg_dump + mongodump backups and SQL migrations on backend deploys,
and pinned curl --resolve health verification. The Expo app is the exception:
it releases through EAS Workflows (aim-store-app/.eas/workflows/), which
build and submit to Google Play automatically on merge. Details in
Deployment.
Monitoring (monitoring/)¶
Grafana + Prometheus + Loki + Tempo + Alloy at monitor.aimstoreorg.com.
Prometheus scrapes the backend's /metrics; Alloy ships container logs to
Loki; Tempo receives the backend's OTLP traces. Dashboards and alert
rules are provisioned from git (see ADR
0007).