Software Requirements (SRS)عربيPrint / PDF

Comestare — Software Requirements Specification (SRS)

Grounded in the actual deployed architecture. Audience: engineers and technical/strategic investors performing technical diligence. Companion: PRD.

1. Introduction

1.1 Purpose

Define the functional and non-functional requirements and the system architecture of the Comestare platform.

1.2 Scope

A bilingual web platform with a customer-facing app, an admin platform, an API gateway, and supporting data stores, delivering AI marketing strategy generation plus self-serve and done-for-you monetization.

1.3 Definitions

  • Universe / strategy — generated marketing strategy (map + roadmap).
  • Gateway / middleware — the API edge that fronts the backends.
  • Route registry — admin-owned config telling the gateway how to proxy/route.

2. System architecture (as built)

                    ┌──────────────────────────┐
   Customers ──────▶│  Frontend (Next.js 15)    │  comestare.com  (Cloudflare)
                    │  EN/AR, RTL, PLG funnel    │
                    └─────────────┬──────────────┘
                                  │ HTTPS (JSON)
                    ┌─────────────▼──────────────┐
                    │  Middleware / API Gateway   │  (NestJS + Fastify)
                    │  auth, JWT, rate-limit,     │  + Redis (sessions,
                    │  caching, proxy, route reg, │    rate-limit, registry)
                    │  Google ID-token verify     │
                    └───────┬───────────┬─────────┘
                            │           │ internal (X-Internal-Token)
              ┌─────────────▼──┐   ┌────▼───────────────┐
              │ Customer-backend│   │  Admin-backend      │
              │ NestJS+Fastify  │   │  NestJS+Fastify     │
              │ users/sessions/ │   │  routes/pricing/    │
              │ OTP/auth        │   │  finance/audit/admins│
              │ Prisma          │   │  Prisma (schema=admin)│
              └────────┬────────┘   └─────────┬───────────┘
                       │                      │
                       └──────────┬───────────┘
                          ┌───────▼────────┐      ┌──────────────┐
                          │  PostgreSQL     │      │  Admin Panel  │
                          │ (public + admin │◀─────│  Next.js      │
                          │  schemas)       │ direct│ (cookie auth)│
                          └─────────────────┘      └──────────────┘

Components:

  1. Frontend — Next.js 15 (App Router), Tailwind, React Query, Zustand, custom i18n (EN/AR + RTL), Google Identity Services; deployed on Cloudflare.
  2. Middleware (gateway) — NestJS/Fastify; JWT access/refresh, rate-limiting, L1 in-memory + Redis caching, route-registry-driven proxy, Google ID-token verification (JWKS), CORS, Helmet.
  3. Customer-backend — NestJS/Fastify + Prisma/Postgres; users, sessions, OTP, password + Google auth, refresh-token records; exposes internal endpoints to the gateway (X-Internal-Token).
  4. Admin-backend — NestJS/Fastify + Prisma/Postgres (admin schema); admins (owner/admin/viewer), route registry (/internal/routes), pricing (public pricing endpoint), finance/wallets, audit; admin JWT (HS256) via HttpOnly cookie.
  5. Admin panel — Next.js; talks directly to admin-backend with cookie session.
  6. Data — PostgreSQL (shared instance, separate schemas); Redis (sessions, rotation, rate-limit, registry cache).

3. Functional requirements (system)

3.1 Auth & sessions

  • SRS-AUTH-1 Email signup with OTP verification; password (argon2) login.
  • SRS-AUTH-2 Google sign-in: frontend obtains a Google ID token; gateway verifies signature + aud (= GOOGLE_CLIENT_ID) + iss against Google JWKS; trusted claims passed to customer-backend.
  • SRS-AUTH-3 Issue JWT access (short TTL) + refresh (rotating, family-based theft detection) tokens; refresh stored hashed in backend + tracked in Redis.
  • SRS-AUTH-4 Refresh cookie HttpOnly/Secure/SameSite; logout revokes family + blocklists access JTI.
  • SRS-AUTH-5 Admin auth is separate (HS256 cookie, roles).

3.2 Gateway

  • SRS-GW-1 Route requests per the admin-owned route registry (with bundled fallback).
  • SRS-GW-2 Per-IP rate limiting with configurable windows; expose limit headers.
  • SRS-GW-3 Cache cacheable upstream responses (L1 + Redis) with TTLs.
  • SRS-GW-4 Normalize locale (URL prefix /en, /ar → Accept-Language) before forwarding.
  • SRS-GW-5 Enforce CORS allow-list; security headers (Helmet).

3.3 Strategy generation

  • SRS-GEN-1 Accept idea/URL; call AI provider; return structured universe + roadmap.
  • SRS-GEN-2 Enforce plan-based usage limits and watermarking.
  • SRS-GEN-3 Persist generated strategies to the user account.
  • SRS-GEN-4 Localize generation to EN/AR.

3.4 Billing & monetization

  • SRS-BILL-1 Subscription management (Free/Starter/Pro/Agency) via Stripe (+ local GCC rails roadmap).
  • SRS-BILL-2 Feature gating by tier.
  • SRS-BILL-3 Services milestone billing; Ad Studio recurring + % of spend.

3.5 Admin

  • SRS-ADM-1 Manage users/sessions/audit, pricing, routes, finance.
  • SRS-ADM-2 Public pricing endpoint consumed by the marketing site.
  • SRS-ADM-3 Push route-registry invalidations to the gateway.

3.6 Leads & analytics

  • SRS-LEAD-1 Capture & store lead records + UTM/attribution + behavioral events.
  • SRS-LEAD-2 Compute lead score and lifecycle stage; route hot leads.

4. Non-functional requirements

4.1 Performance

  • NFR-PERF-1 P95 API latency (non-generation) < 300 ms server-side.
  • NFR-PERF-2 Strategy generation streamed/progressive; perceived completion target < 30 s; show progress.
  • NFR-PERF-3 Cache hot reads (pricing, registry) to protect backends.

4.2 Reliability & availability

  • NFR-REL-1 Target 99.9% uptime for auth + generation paths.
  • NFR-REL-2 Graceful degradation: gateway uses fallback routes if admin-backend unreachable.
  • NFR-REL-3 No 5xx on the auth/sign-in path under normal operation (see Appendix A).
  • NFR-REL-4 Health/readiness endpoints (/healthz, /readyz) with DB checks.

4.3 Security & privacy

  • NFR-SEC-1 All traffic TLS; secrets in env/secret store, never in VCS.
  • NFR-SEC-2 Passwords argon2; JWTs signed; refresh rotation with reuse detection.
  • NFR-SEC-3 Internal service calls authenticated via X-Internal-Token (≥32 bytes).
  • NFR-SEC-4 Rate-limiting + Helmet + strict CORS allow-list.
  • NFR-SEC-5 PDPL (Saudi) + GDPR compliance: explicit consent capture, data-subject rights, data-retention policy, and data-residency option for GCC (see Saudi/GCC Brief).
  • NFR-SEC-6 PII access audited (admin audit trail exists).

4.4 Scalability & cost

  • NFR-SCALE-1 Stateless gateway/back ends horizontally scalable; state in Postgres/Redis.
  • NFR-SCALE-2 Control AI inference cost via free-tier caps, caching, and model tiering.

4.5 Internationalization & accessibility

  • NFR-I18N-1 Full EN/AR parity incl. RTL, Arabic typography, locale-aware formatting.
  • NFR-A11Y-1 WCAG-AA targets for the core funnel.

4.6 Maintainability & observability

  • NFR-OBS-1 Structured logging (pino) with request IDs; optional OpenTelemetry tracing.
  • NFR-OBS-2 Per-channel funnel analytics; error monitoring.

5. Deployment & environments

  • Frontend: Cloudflare (Next.js / OpenNext).
  • Backends & gateway: containerized; orchestrated via Coolify (Nixpacks); env injected per service.
  • Data: managed PostgreSQL + Redis.
  • Service-to-service over a private network by service name; secrets per environment.

6. Constraints & assumptions

  • AI provider availability and pricing affect cost/latency.
  • GCC data-residency may require a regional deployment.
  • Cross-domain auth (frontend vs. gateway domains) constrains cookie strategy.

Appendix A — Known production issues (reliability backlog)

Surface these proactively in technical diligence; they're normal pre-launch hardening, and fixes are understood:

  1. Middleware ↔ customer-backend networking — gateway must reliably resolve the customer-backend service (observed EAI_AGAIN); fix = shared private network + correct host:port. Until fixed, all backend-dependent auth returns 5xx.
  2. Google sign-in config/session — GOOGLE_CLIENT_ID must be set on the gateway (must equal the frontend client ID); verify JWKS egress.
  3. Cross-domain refresh cookie — frontend and gateway on different root domains; finalize cookie/session strategy (or align domains) so sessions persist.
  4. Client-side FedCM/third-party-cookie behavior — Google chooser depends on browser FedCM/cookie state; document supported configurations.

These are tracked, well-understood, and gated before scaling paid acquisition (NFR-REL-3). None require re-architecture.