Skip to content

SRS Overview — How to Read This Specification

The Yam3at Software Requirements Specification (SRS) is the authoritative functional contract between product, design, engineering, and QA. Every feature of the platform — the Event Operating System for the GCC/Arab world — is specified here as a numbered, testable requirement. If a behavior is not in the SRS, it is not in scope; if the implementation contradicts the SRS, the SRS wins until it is formally amended.

Module map

Each SRS module maps to exactly one bounded context of the 12-domain model. Modules are self-contained: a developer should be able to build a module end-to-end from its page plus this overview.

# Module ID prefix Domain(s) File
1 Identity & Authentication SRS-AUTH 1 Identity identity-and-auth.md
2 Vendor Onboarding & Subscriptions SRS-VOS 4 Vendor, 6 Financial vendor-onboarding-and-subscriptions.md
3 Marketplace & Search SRS-MKT 3 Marketplace, 11 Platform marketplace-and-search.md
4 Vendor Listings SRS-LST 4 Vendor, 3 Marketplace vendor-listings.md
5 Events & Planning SRS-EVT 2 Event events-and-planning.md (Part 2)
6 RFQ & Quotations SRS-RFQ 5 Booking rfq-and-quotations.md (Part 2)
7 Booking SRS-BKG 5 Booking booking.md (Part 2)
8 Payments & Financial SRS-PAY 6 Financial payments.md (Part 2)
9 Messaging & Notifications SRS-MSG 7 Communication messaging-and-notifications.md (Part 2)
10 Reviews & Experience SRS-REV 8 Experience reviews-and-experience.md (Part 2)
11 Admin & Operations SRS-ADM 10 Operations, 11 Platform admin-and-operations.md (Part 2)

Shared engines (notification dispatch, messaging, payment abstraction, file storage, search indexing) are specified once — in the module that owns them — and referenced everywhere else. They are never re-specified per user type.

Requirement ID scheme

Every functional requirement carries a permanent ID:

SRS-<MOD>-<NNN>
  • <MOD> is the module prefix from the table above (e.g. AUTH, VOS, MKT, LST).
  • <NNN> is a zero-padded sequence number unique within the module (001–999).
  • IDs are immutable. A requirement is never renumbered. If a requirement is dropped, its ID is retired and marked Deprecated with a pointer to its replacement; the number is never reused.
  • Test cases, tickets, commits, and API docs reference requirements by ID (e.g. "implements SRS-AUTH-014").

Requirement language follows RFC 2119: MUST = mandatory, SHOULD = strongly recommended (deviation requires a written reason), MAY = optional.

Phase tags

Every requirement and feature is tagged with exactly one delivery phase:

Tag Meaning
MVP Required for Kuwait launch. Not negotiable for v1.0.
Scale Post-launch growth phase (AI recommendations, planner suite, wallet, WhatsApp, KSA/UAE expansion, etc.). Data model must accommodate it from day one; UI/logic ships later.
Vision Long-horizon differentiators (AR previews, escrow, ticketing, white-label, marketplace APIs). Architecture must not preclude it; no implementation commitment.

A Scale or Vision tag on a requirement means: design the schema and module boundaries so the feature can be added without migration pain, but do not build the feature for MVP.

Shared conventions (apply to every module)

These conventions are global. Individual modules restate them only when the module adds specifics.

Time

  • All timestamps are stored in UTC (TIMESTAMP/DATETIME in UTC, ISO 8601 Z-suffixed in APIs).
  • All timestamps are displayed in the viewer's local timezone (default Asia/Kuwait, UTC+3, no DST).
  • Date-only business values (event date, availability date) are stored as calendar dates with an explicit timezone context of the vendor's country.

Deletion

  • All user-facing entities use soft delete (deleted_at nullable timestamp). Hard deletes happen only via scheduled purge jobs (e.g. GDPR-style erasure, expired OTP rows) and are themselves audit-logged.
  • Soft-deleted rows are excluded from all queries by default and from search indexes immediately.

Audit logging

  • Every sensitive action MUST produce an immutable audit log entry: authentication events, role/permission changes, vendor approval decisions, subscription/plan changes, payments and refunds, content moderation decisions, account deletion/export, admin impersonation, and any admin write on user data.
  • Audit entries record: actor id + role, action, entity type + id, before/after diff (JSON), IP, user agent, timestamp (UTC). Audit logs are append-only and retained ≥ 5 years.

Bilingual content

  • Yam3at is Arabic-first with full English parity. Every human-readable content field is stored as a pair: name_ar / name_en, description_ar / description_en, etc.
  • For vendor-authored content, one language is mandatory and the other optional; the UI falls back to the filled language with a visual "other language" indicator. Platform-authored content (categories, policy templates, CMS) MUST have both languages before publication.
  • Slugs are ASCII (transliterated from English name); Arabic search matching is handled by the search engine, not the slug.

Money

  • Launch currency is KWD, which has 3 decimal places (1 KD = 1000 fils). All monetary amounts are stored as DECIMAL(12,3) plus an ISO 4217 currency column — never floats, never an assumed currency.
  • Display formatting is locale-aware: د.ك 250.000 (AR) / KWD 250.000 (EN).

Identifiers & API

  • Public identifiers are ULIDs (sortable, non-enumerable). Auto-increment integers never leave the database.
  • All endpoints live under /api/v1/…; list endpoints are cursor-paginated (default 20, max 100 per page) and return the standard envelope { data, meta, links }.
  • Errors use RFC 9457 problem-details JSON with a machine-readable code and a bilingual message_ar/message_en.

Phone numbers

  • Stored in E.164. Kuwait launch: +965 followed by an 8-digit local number; Kuwaiti mobile numbers begin with 5, 6, or 9. Customers are not required to provide a Civil ID; vendors are required to provide a commercial license (see Vendor Onboarding).

Global non-functional requirements

ID Requirement Phase
SRS-NFR-001 API p95 latency ≤ 300 ms and p99 ≤ 800 ms for read endpoints; p95 ≤ 600 ms for write endpoints, measured at the load balancer under nominal load. MVP
SRS-NFR-002 Search-as-you-type responses (Meilisearch-backed) MUST return in ≤ 100 ms p95. MVP
SRS-NFR-003 Web app: Largest Contentful Paint ≤ 2.5 s on a mid-range Android device over 4G for the home, category, and vendor-profile pages. MVP
SRS-NFR-004 Availability target 99.9 % monthly for the API and web app, excluding announced maintenance windows (announced ≥ 48 h ahead, scheduled 02:00–05:00 Asia/Kuwait). MVP
SRS-NFR-005 All customer/vendor-facing surfaces MUST meet WCAG 2.1 AA: contrast ≥ 4.5:1, full keyboard operability, visible focus, labels on all inputs, aria-live for async updates, no information conveyed by color alone. MVP
SRS-NFR-006 Full RTL support: Arabic locale renders mirrored layouts (dir="rtl"), logical CSS properties only, bidirectional-safe rendering of mixed AR/EN strings, Arabic-Indic or Latin digits per locale setting. Every screen is designed RTL-first. MVP
SRS-NFR-007 Security baseline: OWASP ASVS Level 2; TLS 1.2+ everywhere; passwords hashed with Argon2id; secrets in a vault, never in code; rate limiting on all authentication and OTP endpoints; CSRF protection on the web app; signed, expiring URLs for private files; no card data ever touches Yam3at servers (PSP-hosted/tokenized flows only — SAQ-A scope). MVP
SRS-NFR-008 All personal data flows MUST support subject rights: export (machine-readable) and erasure/anonymization within 30 days of a verified request. MVP
SRS-NFR-009 The platform is multi-country/multi-currency/multi-language ready: country, currency, and locale are data, not code. Kuwait is configuration, not assumption. MVP
SRS-NFR-010 Horizontal scalability: stateless API nodes, Redis-backed queues (Horizon), and a search index rebuildable from MySQL as the source of truth. MVP
SRS-NFR-011 Backups: automated daily full + point-in-time recovery for MySQL; RPO ≤ 15 min, RTO ≤ 4 h. Restore drills quarterly. MVP
SRS-NFR-012 Observability: structured JSON logs with correlation IDs, error tracking, uptime and queue-depth alerting before launch. MVP

Standard module structure

Every module page contains these sections in this order — if a section is genuinely empty for a module, it says so explicitly rather than being omitted:

  1. Purpose — what the module owns and does not own.
  2. Actors — who interacts with it.
  3. User stories — "As a …, I want …, so that …".
  4. Functional requirements — numbered SRS-<MOD>-NNN, each phase-tagged.
  5. Business rules — cross-cutting policy decisions.
  6. Validation rules — exact field formats, lengths, limits.
  7. Permissions matrix — actions × roles.
  8. Status / state machine — Mermaid diagram where an entity has a lifecycle.
  9. Edge cases — known tricky scenarios and their required behavior.
  10. Empty / loading / error states — what every screen shows when there is nothing, when it is fetching, and when it fails.
  11. Acceptance criteria — the QA sign-off checklist.
  12. Data entities touched — tables/aggregates the module reads or writes.
  13. Related API endpoints — paths only; full contracts live in the API specification volume.

Change control

Amendments to any requirement go through a product-owner-approved change log entry on the module page. Silent edits to shipped requirements are not permitted.