Skip to content

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/:code click-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 at GET /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 filter sla=grievance_overdue, critical SupportGrievanceBreached alert); 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) when OTEL_EXPORTER_OTLP_ENDPOINT is 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 the mailto: 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 the aimstore scheme.
  • GET /api/health reports {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).