ٽيڪنالاجي فن تعمير

سنڌ آءِ ٽي پورٽل — سهولت ڊيسڪ (SITP) جو سرِ تا سر انجنيئرنگ فن تعمير: اجزاء، پرتون، ڊيٽا، اے آءِ، سيڪيورٽي، تعيناتي، ۽ عملو۔

1. فن تعمير جو جائزو ۽ اصول

SITP کي هڪ API-first، ماڊيولر مونوليث جي طور تي انجنيئر ڪيو ويو آهي جنهن ۾ پلگ ايبل اے آءِ/او سي آر پرت آهي، تعمير جي لحاظ کان گهڻ لساني (EN/UR/Sindhi)، هر پرت تي ڪردار تي مبني دائرو، سرِ تا سر feature-flagged، ۽ observability-first۔ هيٺ مرچڙا اصول هن دستاويز جي هر downstream ڊيزائن فيصلي کي ضابطو ڏين ٿا۔

تعميري اصول

هي فن تعمير مائڪروسروسز جي پکيڙ کان وڌيڪ چند چڱي طرح هلائبا ويندڙ اجزاء کي ترجيح ڏئي ٿو: هڪ app DB، هڪ cache، هڪ سرچ، هڪ object store، هڪ identity provider، هڪ queue، هڪ BI ٽول۔ هي ٽيم جي سائز، Server4Sale تي سنگل هوسٽنگ شروعاتي نقطي، ۽ صوبائي حڪومت جي عملي سادگيءَ جي خواہش سان مطابقت رکي ٿو۔ sewers (interfaces، queues، ماڊيولز) ان طرح ڊيزائن ٿيا آهن جو scale-out، multi-tenant، يا مائڪروسروس ڪڍڻ هڪ refactor آهي، rewrite ناهي۔

2. اعليٰ سطحي فن تعمير ڊاياگرام

پورٽل ٻن عوامي فرنٽ اينڊز (هڪ Next.js مڪمل پورٽل ۽ Docusaurus docs سائيٽ) جي طور تي فراهم ڪيو وڃي ٿو جيڪي nginx reverse proxy جي پويان آهن۔ proxy TLS ختم ڪري ٿو، static docs build براهِ راست serve ڪري ٿو، ۽ /api کي NestJS API gateway، ڊگهي عمر واري WebSocket gateway، Python FastAPI اے آءِ سروس، embedded Metabase، ۽ (admin plane ۾) Keycloak ڏانهن اڳتي موڪلي ٿو۔ API gateway سڀني stateful backends جو واحد داخلي نقطو آهي: MariaDB 10.11 (system of record)، Redis (cache + sessions + queues)، Meilisearch (گهڻ لساني سرچ)، MinIO (S3-متوافق object storage، ClamAV جي پويان)، ۽ BullMQ workers جيڪي OCR/AI/email/SMS/WhatsApp کي offload ڪن ٿا۔ بيروني انضمام — NADRA، SECP، FBR، SRB، PSEB، NITB e-Office، Mailjet، SMS gateways، WhatsApp Business API، Zoom/Meet/Teams — صرف integrations پرت ۾ adapter ماڊيولز ذريعي reachable آهن۔

ڊاياگرام اجزاء کي planes ۾ گروپ ڪري ٿو — Clients، Edge، Application، Identity، Stateful backends، Analytics، ۽ External integrations — تان جو trust ۽ dependency boundaries واضح ٿين۔ NestJS API gateway اهو واحد جزو آهي جيڪو هر stateful backend ۽ گهڻن بيروني انضمامن سان ڳالهائي ٿو؛ workers اسٽوريج، سرچ، ۽ ٻاهرين notification چينلز سان ڳالهائن ٿا؛ اے آءِ سروس صرف object اسٽوريج ۽ Redis (پنهنجي caching/job state لاءِ) سان ڳالهائي ٿي ۽ gateway ۽ workers جي طرفان سڏجي ٿي، clients جي طرفان براهِ راست ناهي۔ WebSocket gateway API سان pub-sub fan-out لاءِ Redis شيئر ڪري ٿو تان جو API يا workers جي طرفان پيدا ٿيل live updates صحيح متصلي sessions تائين پهچن۔

3. اجزاء جي فهرست (Component Catalog)

4. ايپليکيشن پرتون (NestJS)

NestJS تعيناتي کي هڪ کلين فن تعمير ماڊيولر مونوليث جي طور تي منظم ڪيو ويو آهي: هر ماڊيول پنهنجي domain models، DTOs، services، controllers، ۽ persistence جو مالڪ آهي، ۽ ٻين ماڊيولن کي صرف typed interfaces ڏئي ٿو۔ Cross-cutting concerns (validation، auth، logging، tracing، feature flags) shared infrastructure ۾ رهن ٿا جن کي ڪو به domain ماڊيول bypass ناهي ڪندو۔

ماڊيول ميپ

Cross-cutting mechanics

• DTOs & validation. هر request body هڪ class-validated DTO (class-validator + class-transformer) آهي؛ hot paths لاءِ Zod-متوافق runtime schemas۔ ڪابه raw any payloads controller boundary کي cross ناهي ڪندي۔
• Guards. AuthGuard (OIDC/JWT)، RolesGuard (RBAC)، PermissionsGuard (granular per-permission overrides)، FeatureFlagGuard (flag بند هجي تي route kill)، StepUpGuard (حساس actions لاءِ ٻيهر چئلنج)، ThrottlerGuard (rate limit)۔
• Interceptors. LoggingInterceptor، TracingInterceptor (OTel)، AuditInterceptor (append-only)، LocaleInterceptor (request context ۾ صارف locale propagate)۔
• Pipes. whitelist + forbidNonWhitelisted سان Global validation pipe؛ هڪ TransformPipe جيڪو dates کي UTC ۽ locale-aware strings ۾ normalize ڪري ٿو۔
• Queue offloading. جيڪو > 250 ms جو تخمينو آهي يا بيروني سروس کي call ڪري ٿو اهو inline هلائڻ بدران BullMQ ۾ enqueue ڪيو وڃي ٿو: OCR، LLM/translation/transcription، email/SMS/WA fan-out، PDF/Excel export، scheduled digests، escalation timer ticks۔ هر job class جو پنهنجو queue ۽ worker pool free، independent concurrency ۽ backpressure سان۔
• Transactions. اهڙا domain services جيڪي multiple aggregates کي touch ڪن ٿا اهي explicit MariaDB transactions استعمال ڪن ٿا؛ long-running work کي DB transaction مان ٻاهر منتقل ڪيو وڃي ٿو (transaction جي اندر enqueue ڪريو، commit کان پوءِ ڪم ڪريو) تان جو row-lock dwell time مختصر رهي۔

5. ڊيٽا بيس

5.1 انتخاب: MariaDB 10.11 (PostgreSQL ناهي)

System of record MariaDB 10.11.14 آهي، جيڪو اڳ ۾ئي production هوسٽ تي انسٽال ۽ هلندڙ آهي۔ هي هڪ سوچيل سمجهيل، locked فيصلو آهي (_context.md §3 ڏسو)۔ PostgreSQL هن stack ۾ ڪٿي به استعمال ناهي ٿيندو۔ سبب:

• هوسٽ provisioned آهي ۽ DBA/ops tooling MariaDB جي چوڌاري ٺاهي وئي آهي۔
• MariaDB 10.11 uuid()، sys schema بهترايون، JSON (LONGTEXT جي طور تي validation functions سان)، DML تي RETURNING، SEPARATOR window-function refinements، ۽ sequences لاءِ or replace آڻي ٿو — جيڪي سڀ هن پروڊڪٽ جون ضرورتون cover ڪن ٿا۔
• پروڊڪٽ جو ڪو به PostgreSQL-only انحصار ناهي (ڪو pgvector ناهي — vector سرچ ۽ semantic سرچ Meilisearch ۽ اے آءِ سروس کي سونپيل آهن؛ PostGIS ۾ ڪابه ڀاري GIS ناهي — ضلعو heatmap bounding-box math يا lightweight spatial index استعمال ڪري ٿو؛ MariaDB جي support کان اڳيان ڪابه advanced window functions ناهي)۔

5.2 ORM تجويز: Prisma

Locked stack ۾ Prisma ۽ TypeORM ٻئي قابلِ قبول طور تي درج آهن۔ SITP لاءِ Prisma تجويز ٿيل آهي ڇاڪاڻ ته:

1. First-class MariaDB/MySQL driver. Prisma جو connector MySQL/MariaDB wire protocol کي natively target ڪري ٿو؛ ڪابه ORM-internal SQL translation surprises ناهي۔
2. Type safety سرِ تا سر هڪ ئي schema.prisma source of truth مان، جيڪو TypeScript-primary ٽيم جي رفتار وڌائي ٿو۔
3. Migrations explicit، reviewable، ۽ CI-gated آهن — هڪ اهڙي حڪومتي system لاءِ اهم جتي schema change auditable آهي۔
4. ماڊيولر مونوليث لاءِ بهتر developer ergonomics (هڪ generator، هڪ client، schema // <-- module --> comments ۽ prismaSchemaFolder previews ذريعي divided)، جيڪو MAAHIR انجنيئرن جي وچ ۾ onboarding friction گهٽ ڪري ٿو۔
5. Raw escape hatch (prisma.$queryRaw) انهن چند cases لاءِ جن کي MariaDB-specific SQL گهرجي (جهڙوڪ RETURNING، materialized-view refresh)۔

Caveat: Prisma اڃا تائين ڪنهن JSON operations لاءِ MariaDB سرور ورژن quirks auto-detect ناهي ڪندو؛ JSON columns لاءِ اسان انهن کي String (validated JSON) جي طور تي model ڪندا آهيون ۽ ضرورت پوڻ تي $queryRaw ذريعي MariaDB جا JSON_* functions استعمال ڪندا آهيون۔ اهڙين cases جو حجم گهٽ آهي۔

5.3 Schema حڪمتِ عملي

• في bounded concern هڪ logical schema، سڀ ساڳئي MariaDB ڊيٽا بيس ۾۔ ماڊيول tables prefixed آهن (مثال طور، tkt_، org_، fil_، not_، ai_، int_، aud_) تان جو ماڊيول ownership ڊيٽا بيس.split ڪرڻ کان سواءِ ظاهر ٿئي۔
• Append-only آڊٽ table (aud_event) هر state-changing action لاءِ؛ ڪڏهن به update يا delete ناهي ٿيندو، مهيني جي لحاظ کان partitioned۔
• deleted_at ذريعي soft deletes صارف-facing records لاءِ؛ hard deletes صرف GDPR/RTI-driven purges لاءِ، هڪ scheduled job جي طور تي۔
• Enum جهڙيون lookup tables جي طور تي Status، ticket/MoM/registration states لاءِ free-text columns ناهي۔
• Money integer minor units (PKR paisa) جي طور تي explicit scale سان محفوظ، ڪڏهن به floating point ناهي۔
• Timestamps UTC (DATETIME(6)) جي طور تي محفوظ؛ locale formatting هڪ application concern آهي۔
• Identifiers: بامعنيٰ ٽِڪيٽ IDs SITP-YYYY-<DEPT>-<NNNNNN> هڪ display column آهن جيڪي BIGINT/UUID surrogate primary key سان آهن (تان جو renumbering، merge، ۽ sharding ممڪن رهي)۔

5.4 Character set

• ڊيٽا بيس، tables، ۽ text columns: utf8mb4 collation utf8mb4_unicode_520_ci (UCA-based، Urdu ۽ Sindhi لاءِ صحيح ordering) سان۔ legacy utf8 (3-byte) استعمال نہ ڪريو — اهو Sindhi لاءِ گهرجندڙ سڀ Arabic-script characters store ناهي ڪري سگهندو۔
• Connection charset: Prisma datasource URL ۽ MariaDB user default تي utf8mb4 enforced۔
• Server setting: character_set_server=utf8mb4، collation_server=utf8mb4_unicode_520_ci۔

5.5 Indexing

• هر table تي primary keys (surrogate BIGINT يا UUID)۔
• Hot access paths تي composite indexes: ٽِڪيٽ queues لاءِ (org_id, status, updated_at)؛ "my work" لاءِ (assignee_id, status)؛ escalation scans لاءِ (dept_id, sla_due_at)۔
• اهڙا foreign keys index ڪريو جن کي MariaDB auto-index ناهي ڪندو (مثال طور، 1:N جي child تي)۔
• سڀ کان وڌيڪ frequent dashboard group-by queries لاءِ covering indexes؛ EXPLAIN ANALYZE ذريعي سه ماهي review۔
• Full-text سرچ MariaDB تي primary path ناهي — Meilisearch گهڻ لساني full-text جو مالڪ آهي۔ MariaDB FULLTEXT indexes صرف exact-phrase Latin queries لاءِ fallback جي طور تي استعمال ٿين ٿا۔

5.6 Read replicas (مستقبل)

اڄ SITP هڪ ئي MariaDB instance تي هلندو آهي۔ فن تعمير read replicas شامل ڪرنجو آپشن کلي رکي ٿو براءِ: Metabase analytics reads، reporting/exports، ۽ read-heavy عوامي سائيٽ queries۔ Prisma client ان نقطي تي read/write split سان configure ڪيو ويندو؛ سڀ writes (۽ write transactions جي اندر reads) primary ڏانهن ويندا، analytics/dashboard reads replicas ڏانهن ويندا۔ Replication lag هڪ configured threshold کان bounded آهي؛ laggy replicas automatically skip ٿيندا آهن۔

5.7 Backups

• Logical: روزانو mariadb-dump (per-database، --single-transaction --routines --triggers --events) MinIO ۽ Server4Sale off-host اسٽوريج ڏانهن ship۔
• Physical: تيز point-in-time recovery جي قابل بنائڻ لاءِ هڪ schedule تي MariaDB binary backup (mariabackup)۔
• Binary log: enabled ۽ §22 ۾ RPO پورو ڪرڻ لاءِ ڪافي عرصي تائين retained۔
• Restore drills: هڪ isolated ماحول ۾ سه ماهي restore، runbook سان ڳنڍيل checksum report سان۔

6. اے آءِ / OCR فن تعمير

6.1 انجن abstraction (پلگ ايبل)

FastAPI اے آءِ سروس ٽي مستحڪم interfaces ڏئي ٿي۔ هر consumer (NestJS ماڊيول يا BullMQ worker) interface لاءِ programme ڪري ٿو، ڪڏهن به vendor SDK لاءِ ناهي۔

# Illustrative interface contract (per engine family)
class AIClient(Protocol):
    async def complete(self, req: AIRequest) -> AIResponse: ...
    async def embed(self, req: EmbedRequest) -> EmbedResponse: ...

class OCRClient(Protocol):
    async def extract(self, req: OCRRequest) -> OCRResult: ...

class TranscriptionClient(Protocol):
    async def transcribe(self, req: AudioRequest) -> Transcript: ...

هر interface جا multiple concrete adapters آهن۔ سروس ڪال جي وقت في feature ۽ في ڊيٽا-حساسيت class هڪ adapter چونڊتي ٿي، استعمال ڪندي (a) feature-flag سروس، (b) input جي ڊيٽا classification، ۽ (c) environment-level allow-list (تان جو هڪ "خود مختار" ماحول ڪلائوڊ انجنز کي مڪمل طور تي منع ڪري سگهي)۔

6.2 اے آءِ request flow

هر اے آءِ ڪال جو هڪ ئي shape آهي: policy resolve ڪريو → هن feature+sensitivity لاءِ انجن resolve ڪريو → PII redact ڪريو → call ڪريو → ناڪامي تي، fall back ڪريو → log + audit ڪريو → respond ڪريو۔ تحريري وضاحت ڊاياگرام جي پيروي ڪري ٿي۔

flow چار invariants يقيني بڻائي ٿو: (1) ڪو به اهڙو انجن ڪڏهن به call ناهي ٿيندو جنهن جي policy input جي sensitivity class لاءِ disallow ڪري ٿي؛ (2) PII ان وقت کان اڳ redact ٿي وڃي ٿو جنهن payload trusted boundary ڇڏي ٿو جيڪڏهن ڪلائوڊ انجن چونڊيل هجي؛ (3) ڪنهن به single انجن جي ناڪامي fallback ذريعي recoverable آهي تان جو صارف-facing feature دستياب رهي؛ (4) هر ڪال — بشمول ان جو انجن، latency، cost، ۽ redacted PII tokens جو تعداد — شفافيت ۽ cost governance لاءِ هڪ immutable آڊٽ row ۾ capture ٿئي ٿو۔

6.3 11 اے آءِ صلاحيتون ۽ انجن رهنمائي

6.4 PII redaction ۽ on-prem fallback

PII redaction هر flow ۾ پهرين هلندو آهي۔ انهن inputs لاءِ جن جي ڊيٽا class ڪلائوڊ پروسيسنگ forbidden ڪري ٿي (مثال طور، raw CNIC، NADRA payloads، خفيه/VIP ٽِڪيٽ)، selector ڪال کي on-prem path (Llama/Qwen + Tesseract/Whisper) ڏانهن route ڪري ٿو۔ Redaction پرت downstream موڪليل redacted payload ۽ هڪ reversible mapping (صرف ڪال جي duration لاءِ memory ۾ رکيل، ڪڏهن به persist ناهي ٿيندو) ٻئي output ڪري ٿي تان جو final response کي caller ڏانهن موٽائڻ کان اڳ re-hydrate ڪري سگهجي۔ هي §1 جي data-residency-aware اصول کي پورو ڪري ٿو۔

7. Real-time پرت

WebSocket gateway چار classes جي live تجربي کي طاقت ڏئي ٿو:

1. ٽِڪيٽ updates — status، assignment، SLA، watcher notifications، file attachments۔
2. Presence ۽ typing — ٽِڪيٽ-scoped threads ۽ اندروني مواصلات لاءِ۔
3. 3-tier اندروني مواصلات — (1) ٽِڪيٽ-scoped private threads، (2) org-wide inbox DMs/groups، (3) مڪمل Slack-style channels (threads، pins، read receipts)۔
4. Live dashboards — role dashboards ۾ analytics push (مثال طور، open-ticket counts، SLA breach alerts)۔

gateway connections کي Keycloak tokens جي خلاف authenticate ڪري ٿو (connect ۽ periodic refresh تي verified)، هر subscription کي RBAC ۽ ABAC جي خلاف authorize ڪري ٿو، ۽ ڪڏهن به client-asserted scope تي اعتبار ناهي ڪندو۔ Scaling: جڏهن هڪ کان وڌيڪ gateway instances گهرجن، سڀ instances هڪ Redis pub-sub adapter شيئر ڪن ٿا تان جو ڪنهن به NestJS ماڊيول يا ڪنهن به BullMQ worker جي طرفان ڪنهن به هوسٽ تي پيدا ٿيل event صحيح متصلي session تائين پهچي خواه اهو ڪنهن به instance تي هجي۔ Backpressure per-connection سنڀاليو وڃي ٿو (ٽِڪيٽ updates drop ڪرڻ کان اڳ typing indicators drop ڪريو) ۽ gateway connect/disconnect/message لاءِ OTel spans emit ڪري ٿو تان جو Loki/Grafana plane latency ۽ drops کي correlate ڪري سگهي۔

8. سرچ (Meilisearch)

MariaDB full-text Urdu ۽ Sindhi scripts لاءِ ڪمزور آهي؛ Meilisearch پورٽل ۾ گهڻ لساني سرچ جو مالڪ آهي۔

• ڇا index ٿئي ٿو: ٽِڪيٽ (title، description، status، محڪمو، requester)، KB مضمون (title، body، attachments-as-text)، آفيسرن (Brand & Officials CMS مان)، دستاويزن (OCR کان پوءِ extracted text)، ۽ چيٽ پيغامات (3-tier comms)۔
• Indexing pipeline: NestJS ماڊيولز ۽ BullMQ workers system of record جي طور تي MariaDB ۾ لکن ٿا؛ هڪ search-indexer worker domain events (يا change streams polls) ٻڌندو آهي ۽ normalized، redacted دستاويزون Meilisearch ڏانهن push ڪندو آهي۔ PII indexing کان اڳ redact ٿئي ٿي؛ خفيه/VIP ٽِڪيٽ policy مطابق exclude يا mask ٿيندا آهن۔
• گهڻ لساني tokenization: Meilisearch جو built-in Roman/Arabic-script normalization Urdu ۽ Sindhi کي قابلِ قبول طور تي سنڀاليندو آهي؛ locale في دستاويز محفوظ آهي ۽ queries صارف جي locale carry ڪن ٿيون تان جو result ranking same-language matches کي ترجيح ڏئي سگهي۔
• سرچ API surface: NestJS API Meilisearch سان /search (۽ scoped variants جهڙوڪ /search/tickets، /search/kb) ڏئي ٿو، role-scoped filtering سان تان جو هڪ requester ٻي ڪمپني جي ٽِڪيٽ ۾ سرچ نه ڪري سگهي۔
• Re-indexing: indexes versioned آهن؛ re-indexing هڪ shadow index ۾ ٿئي ٿي جيڪا schema تبديلين دوران سرچ downtime کان بچڻ لاءِ atomically swap ٿئي ٿي۔

9. اسٽوريج ۽ فائلون

• Object store: MinIO (S3-متوافق)، ساڳئي هوسٽ تي deploy۔ في content class Buckets: uploads، generated-docs، moms، avatars، exports۔ سڀ buckets باقي ۾ encrypted (MinIO KMS يا SSE-S3) ۽ versioned آهن۔
• AV scan pipeline: هر upload هڪ ClamAV worker ۾ enqueue ٿئي ٿي؛ فائل scan جي clean return تائين quarantine ٿئي ٿي (ٻين صارفين کي نظر ناهي ايندي)۔ Infected files isolate ٿين ٿيون ۽ هڪ آڊٽ event raise ٿئي ٿو؛ requester کي in-app notify ڪيو وڃي ٿو۔
• Presigned URLs: سڀ downloads هڪ authorization check کان پوءِ API ذريعي minted time-limited presigned URLs مان گذرن ٿيون؛ URLs منٽن ۾ expire ٿين ٿيون، جتي ممڪن هجي requesting صارف سان bound ٿين ٿيون، ۽ log ٿين ٿيون۔
• Retention linkage: هر فائل پنهنجي source record (ٽِڪيٽ، MoM، KB article) سان هڪ fil_attachment row ذريعي linked آهي؛ retention rules (ڊيٽا-classification policy مان، §16 ڏسو) هڪ scheduled cleanup worker هلائين ٿيون جيڪا links revoke ڪري ٿي، presigned URLs expire ڪري ٿي، ۽ (retention window کان پوءِ) object purge ڪري ٿي۔
• Backup: MinIO buckets راتو رات off-host اسٽوريج ڏانهن mirror ٿين ٿيون؛ versioning accidental overwrites لاءِ point-in-time recovery ڏئي ٿو۔

10. Identity ۽ Auth

• Keycloak identity provider آهي، جيڪو NestJS API ۽ Next.js پورٽل سان OIDC ڳالهائي ٿو۔ ٻه realm classes: هڪ حڪومتي عملي لاءِ (جتي ممڪن هجي موجوده حڪومتي IdP سان federate)، ۽ هڪ ڪمپني نمائندن / شهرين لاءِ۔
• 2FA: عملي لاءِ default طور تي TOTP (Authenticator apps)؛ device support limited هجي تي fallback يا ڪمپني نمائندن لاءِ SMS OTP۔ Step-up auth حساس actions (VIP ٽِڪيٽ بند ڪرڻ، record delete ڪرڻ، حساس analytics export ڪرڻ، Primary Authorized Rep بدلائڻ) لاءِ صارف کي ٻيهر چئلنج ڪري ٿو۔
• Sessions/JWT: مختصر عمر access tokens (منٽ)، ڊگهي عمر refresh tokens (ڏينهن)، ٻئي ئي تيز enforcement لاءِ Redis ۾ mirror ٿيل Keycloak-side denylist ذريعي revocable۔
• RBAC enforcement * ٻن* پرتن تي هلندو آهي: API پرت (RolesGuard / PermissionsGuard) coarse route-level رسائي لاءِ، ۽ ڊيٽا پرت (Prisma query extensions / row-level scopes) تان جو logged-in عملي جو فرد به صرف اهي ئي ٽِڪيٽ پڙهي سگهي جن جو حق سندس role ۽ محڪمي ڏنو آهي۔ خفيه/VIP ٽِڪيٽن لاءِ، هڪ ABAC check RBAC ۾ وڌائي ٿو: صرف explicitly listed watchers ۽ escalation chain پڙهي سگهن ٿا۔
• آڊٽ: هر login، step-up، role change، ۽ permission override append-only آڊٽ لاگ ۾ لکيو وڃي ٿو۔

11. Feature Flag سروس

system جي هر صلاحيت سپر ايڊمن ذريعي، في محڪمي ۽ في ماحول toggleable آهي۔

• اسٽوريج: flags MariaDB (ffg_flag، ffg_override) ۾ رهن ٿا جن جي اڳيان Redis cache آهي؛ reads sub-millisecond آهن۔
• Resolution order: environment default → محڪمو override → user-segment override → off۔ پهريون match کٽي ٿو۔
• Gating: code paths هڪ thin FeatureFlags client ذريعي flags check ڪن ٿا۔ FeatureFlagGuard هڪ پورو route short-circuit ڪري سگهي ٿو؛ services جي اندر، flags logic branch ڪن ٿا (مثال طور، "جيڪڏهن MoM-transcription on آهي، ته audio بہ transcribe ڪريو؛ ٻي صورت upload-only")۔
• Caching ۽ invalidation: flags في request cache ٿين ٿا ۽ admin جي change save ڪرڻ تي Redis pub-sub ذريعي invalidate ٿين ٿا، تان جو toggles redeploy کان سواءِ سيڪنڊن ۾ effect وٺن۔
• آڊٽ: هر flag change (who، what، when، before/after) aud_event ۾ record ٿئي ٿو ۽ admin UI ۾ ڏيکاريو وڃي ٿو؛ current flag set reproducibility لاءِ JSON جي طور تي exportable آهي۔
• Bootstrap flags: اهم defaults (مثال طور، "AI enabled"، "two-way inbound email") migrations ۾ seed ٿين ٿا تان جو هڪ تازو ماحول known state ۾ شروع ٿئي۔

12. Notifications Pipeline

pipeline هڪ single domain event (مثال طور، "ticket updated") کي وصول ڪندڙ جي ترجيحن مطابق multiple channels ڏانهن fan-out ڪري ٿو۔

هڪ domain event dispatcher تائين پهچي ٿي، جيڪو per-recipient channels (email/SMS/WhatsApp/in-app)، locale، ۽ preference-center settings (digest بمقابله immediate، quiet hours، per-channel opt-ins) resolve ڪري ٿو۔ Templates وصول ڪندڙ جي locale ۾ server-side render ٿين ٿيون Gregorian ۽ Hijri ٻئي dates سان۔ هر message هڪ per-channel BullMQ queue ۾ enqueue ٿئي ٿي تان جو WhatsApp outage email کي block نه ڪري۔ Outbound adapters Mailjet، SMS gateway، WhatsApp Business API، ۽ in-app WebSocket push کي call ڪن ٿا۔

Two-way inbound هڪ first-class path آهي: inbound email replies (Mailjet جي inbound parse ذريعي) ۽ inbound WhatsApp replies (WhatsApp webhook ذريعي) parse ٿين ٿيون، ٽِڪيٽ subject/recipient ۾ reference مان resolve ٿئي ٿو، ۽ message ٽِڪيٽ thread ۾ append ٿئي ٿي، normal watcher notifications کي trigger ڪندي۔ Rate limiting provider throttling کان بچڻ ۽ صارف quiet hours جو احترام ڪرڻ لاءِ في channel، في وصول ڪندڙ، ۽ في tenant لاگو ٿئي ٿو۔ Digests ۽ preference center صارفين کي non-urgent notifications batch يا mute ڪرڻ ڏين ٿا۔

13. Integrations پرت

integrations ماڊيول هر بيروني حڪومتي ۽ third-party system کي هڪ adapter جي پويان ڏئي ٿو۔ system باقي ڪو به vendor SDK براهِ راست import ناهي ڪندو۔

Cross-cutting concerns:

• Idempotency: هر outbound call هڪ idempotency key carry ڪري ٿي؛ retries ڪڏهن double-write ناهي ڪندي۔
• Exponential backoff + jitter سان retries؛ max attempts ۽ permanently-failed calls لاءِ هڪ dead-letter queue۔
• Circuit breakers في adapter (مثال طور، Opossum) تان جو بيروني outage gracefully degrade ٿئي بدران cascade جي۔
• Secrets هر adapter لاءِ secrets vault (§16 ڏسو) ۾ رهن ٿا، repo ۾ env files ۾ ڪڏهن به ناهي۔
• آڊٽ: هر outbound call ۽ هر inbound webhook payload (حساس fields redacted سان) int_call ۾ record ٿئي ٿو۔

14. Analytics ۽ BI

• MariaDB ۾ aggregates: Analytics ماڊيول materialized views ۽ lightweight cubes (scheduled workers ذريعي refreshed) maintain رکي ٿو تان جو dashboard reads transactional tables کي hit نه ڪن۔ replicas متعارف ٿيڻ کان پوءِ (§5.6 ڏسو) heavy historical queries هڪ read replica جي خلاف هلن ٿيون۔
• Metabase: self-hosted ۽ اندروني ڪردارن لاءِ signed URLs ذريعي embedded؛ هڪ dedicated analytics schema/replica جي خلاف read-only هلندو آهي۔ ad-hoc exploration ۽ operational reporting لاءِ استعمال۔
• Custom dashboards: ست role dashboards، GIS/ضلعو heatmap، ۽ عوامي شفافيت ڊيش بورڊ لاءِ Next.js پورٽل ۾ ECharts/Recharts۔ عوامي-facing dashboards هڪ separate denormalized table (scheduled worker ذريعي populated) مان anonymized aggregates (ڪابه PII، ڪو به individually-identifiable ڊيٽا ناهي) پڙهن ٿيون۔
• Live push: منتخب dashboard tiles real-time counts (مثال طور، هن ڪلاڪ جا open ٽِڪيٽ) لاءِ WebSocket gateway subscribe ڪن ٿا۔
• Exports: server-side PDF via Puppeteer (letter-quality reports لاءِ) ۽ Excel (هڪ Node library ذريعي) BullMQ workers ذريعي generated؛ export تيار ٿيڻ تي صارف کي notify ڪيو وڃي ٿو ۽ download هڪ presigned URL ذريعي ٿئي ٿي۔
• Scheduled digests: هڪ cron-driven BullMQ job daily/weekly cadences تي per-role/per-محڪمو digests تيار ڪندي آهي، گهڻ لساني render ۽ notifications pipeline ذريعي موڪليون وڃن ٿيون۔

15. گهڻ لساني / i18n / RTL

• ٻوليون: EN (master/source)، UR، Sindhi — ٽيئي first-class سمجهيا وڃن ٿا۔ backend في صارف locale store ۽ JWT ۽ هر job payload ذريعي propagate ڪري ٿو، تان جو templates، سرچ ranking، ۽ اے آءِ ترجمو سڀ صحيح locale receive ڪن بنا صارف کي ٻيهر پڇڻ جي۔
• RTL: renderer ذريعي سنڀاليو وڃي ٿو (docs لاءِ Docusaurus locale؛ پورٽل لاءِ Next.js dir switching)۔ ڪابه inline direction hacks ناهي؛ layout logical properties (padding-inline-start، وغيره) استعمال ڪري ٿو تان جو هڪ single component tree ٻنهي directions serve ڪري۔
• Dual calendar: Gregorian ۽ Hijri گڏ display (حڪومتي convention)۔ Date formatting هڪ locale-aware formatter مان گذري ٿي جيڪا ٻئي emit ڪري ٿي؛ storage هميشه UTC Gregorian آهي، Hijri presentation تي derive ٿئي ٿي۔
• Translation workflow: source مواد (KB مضمون، circulars، SOPs) EN ۾ لکيو وڃي ٿو ۽ _glossary.md constraints استعمال ڪندي اے آءِ translation صلاحيت (§6.3 #6) ذريعي UR/Sindhi ۾ translate ٿئي ٿو؛ publication کان اڳ human reviewers approve ڪن ٿا۔ هر content item جي ترجمي جي status track ٿئي ٿي۔
• Backend اسٽوريج: usr_user ۽ هر content row تي locale؛ localized columns هڪ *_en / *_ur / *_sd pattern يا module جي ضرورت مطابق هڪ json map استعمال ڪن ٿا، في table هڪ ڀيرو decided ۽ consistently لاگو۔

16. سيڪيورٽي فن تعمير

• باقي ۾ خفيه ڪاري: MariaDB (table-level/TDE جتي support هجي)، MinIO (bucket SSE)، ۽ backups سڀ encrypted۔ Keys secrets vault / KMS ذريعي manage ٿين ٿا، images ۾ embed ناهي۔
• منتقلي ۾ خفيه ڪاري: TLS nginx تي terminate؛ جتي ممڪن هجي internal service-to-service هوسٽ نيٽ ورڪ جي اندر TLS هلندو آهي؛ سڀ بيروني provider calls certificate validation سان HTTPS۔
• Secrets management: هڪ secrets vault (مثال طور، HashiCorp Vault، يا Server4Sale-managed secrets store) DB passwords، provider API keys، signing keys رکي ٿو۔ Applications startup تي fetch ڪن ٿيون؛ repo ۾ ڪجهه commit ناهي۔
• RBAC + ABAC: §10 مطابق — coarse route guards plus row-level scoping؛ خفيه/VIP ٽِڪيٽن لاءِ explicit ABAC inclusion لازمی۔
• آڊٽ ٽريل: append-only (aud_event)، مهيني جي لحاظ کان partitioned، off-host اسٽوريج ڏانهن export؛ hash chaining ذريعي tampering detectable۔
• Rate limiting ۽ WAF: nginx-level rate limits ۽ OWASP CRS (modsecurity) API جي اڳيان؛ @nestjs/throttler ذريعي NestJS ۾ per-user throttling Redis سان۔
• Pen-testing plan: هر وڏي release کان اڳ ۽ security-sensitive تبديلي کان پوءِ scheduled external penetration tests؛ findings closure تائين track۔
• CERT-PK هم آهنگي: incident-response runbook CERT-PK notification expectations مطابق؛ ops runbook ۾ contact ۽ escalation paths maintain۔
• CII رجسٽريشن: SITP کي پاڪستان جي framework هيٺ Critical Information Infrastructure سمجهيو وڃي ٿو؛ رجسٽريشن pursued ۽ مٿيان controls CII posture جي support ڪن ٿا۔
• ڊيٽا classification ۽ retention: هر record هڪ ڊيٽا class (Public / Internal / Confidential / Restricted) سان tag؛ §9 ۾ retention rules cleanup drive؛ archival سنڌ Archives rules مطابق۔
• تفصيلي سيڪيورٽي ۽ compliance controls: 16-security-and-compliance/en.md ڏسو۔

17. تعيناتي ۽ هوسٽنگ

Provider: SITP Server4Sale تي hosted آهي ("Powered by Server4Sale")۔ تفصيلي hosting topology TBD آهي، مگر provider fixed آهي۔ هوسٽ تي verified سرور ماحول هي آهي:

Static docs site nginx ذريعي https://sindhitportal.maahir.io/docs/ تي Docusaurus static build output مان براهِ راست serve ٿئي ٿي۔

reverse proxy واحد ingress آهي۔ Static plane Docusaurus build آهي جيڪا disk مان سڌي serve ٿئي ٿي۔ App plane Docker containers جي طور تي هلندي آهي — portal، API، WebSocket gateway، اے آءِ سروس، BullMQ worker pools، Metabase، ۽ Keycloak — هر هڪ پنهنجي container ۽ resource limits سان۔ Stateful plane — MariaDB 10.11، Redis، Meilisearch، MinIO + ClamAV — هوسٽ تي هلندي آهي (MariaDB OS level تي اڳ ۾ئي انسٽال آهي ۽ containers سان local نيٽ ورڪ تي share)۔

Orchestration: اڄ Docker Compose، جڏهن deployment footprint هڪ single هوسٽ کان وڌي تي Kubernetes تائين وڃڻ جو آپشن۔ Compose file ان طرح structured آهي جو هر service definition صاف طور تي هڪ مستقبل جي Kubernetes manifest سان map ٿئي ٿي (في Deploy هڪ service، clear healthchecks، explicit resource requests/limits، secrets as env-from)۔

18. Observability

• Logs: هر سروس مان structured JSON logs، Loki ڏانهن ship؛ trace_id ۽ user_id ذريعي correlated۔
• Metrics: Grafana ۾ application ۽ infrastructure metrics (جتي مفيد هجي Prometheus-style exposition؛ MariaDB exporter، Redis exporter، nginx exporter، Node exporter)۔
• Traces: NestJS، FastAPI اے آءِ سروس، ۽ BullMQ workers ۾ OpenTelemetry instrumentation؛ traces Grafana Tempo يا متوافق ۾ collect ۽ visualize۔
• Errors: client- ۽ server-side error aggregation لاءِ Sentry، release health ۽ source maps سان۔
• Uptime ۽ status: هڪ public status page جيڪو portal، API، docs site، ۽ notifications health report ڪري ٿو؛ Grafana ۾ اندروني SLO dashboards۔

19. CI/CD

• Pipeline (locked stack مطابق GitHub Actions يا GitLab CI): هر push تي — lint → typecheck → unit tests → build۔ main تي merge تي — full integration test suite، container build، ۽ registry ڏانهن push۔
• ماحول: dev → staging → prod، staging ۽ prod کان اڳ manual approval gates۔
• ڊيٽا بيس migrations: Prisma migrations target ماحول جي خلاف هڪ gated، pre-deploy step جي طور تي هلن ٿا؛ migrations forward-only ۽ جتي محفوظ هجي reversible؛ rollback هڪ deliberate، reviewed migration آهي، automated revert ناهي۔
• Deploy: containers Compose ذريعي pull ۽ recreate (اڄ)؛ rolling updates downtime گهٽ۔ Healthchecks cutover gate؛ nginx پراڻو container remove ڪرڻ کان اڳ drain۔
• Hotfix path: هڪ fast-track pipeline branch ساڳيون quality gates سان مگر expedited approvals۔

20. Scalability ۽ Performance

• Caching: Redis hot reads (RBAC resolution، feature flags، KB lookups، dashboard aggregates) explicit TTLs ۽ pub-sub invalidation سان cache ڪري ٿو۔ Cache misses MariaDB مان fall through ۽ re-populate۔
• Queue offload: long-running work (OCR، اے آءِ، exports، fan-out) enqueue ٿئي ٿي — §4 ۽ §12 ڏسو — تان جو request path تيز رهي۔
• Read replicas: analytics ۽ read-heavy عوامي paths لاءِ planned — §5.6 ڏسو۔
• CDN: static assets (portal bundles، docs site، images) nginx جي اڳيان CDN ذريعي serve؛ PWA assets client-side cache۔
• Connection pooling: Prisma جو connection pool MariaDB جي max_connections مطابق sized؛ long-lived workers pooled connections reuse؛ transient serverless-style callers کان بچايو وڃي ٿو۔
• Target NFRs (non-functional requirements — authoritative list لاءِ 03-non-functional-requirements/en.md ڏسو): فن تعمير اتي set latency، throughput، availability، ۽ concurrency targets پورا ڪرڻ لاءِ sized آهي؛ capacity reviews هر سه ماهي Grafana dashboards جي خلاف run۔

21. Disaster Recovery (بنيادي)

بنيادي DR هڪ locked non-functional requirement آهي؛ تفصيلي runbooks deferred۔ بنيادي posture:

• Backups: MariaDB logical + physical + binlog (§5.7)؛ MinIO bucket mirror؛ Keycloak realm export؛ Metabase configuration export۔ سڀ off-host ship۔
• RPO target: placeholder — DR runbook ۾ confirm ٿيندو؛ current capability binlog shipping ذريعي low single-digit منٽ support ڪري ٿو۔
• RTO target: placeholder — DR runbook ۾ confirm ٿيندو؛ current capability mariabackup restore ذريعي ساڳئي هوسٽ تي ڪلاڪن ۾ recovery، ۽ off-host recovery هڪ ڊگهي window ۾ support ڪري ٿو۔
• Failover: اڄ single-host؛ هڪ warm standby هوسٽ ۽ DNS-level failover documented next step۔
• Drills: سه ماهي restore drills، نتيجا runbook سان ڳنڍيل۔

تفصيلي runbooks (per-service recovery، contact tree، comms templates) هڪ separate operational دستاويز جي طور تي تيار۔

22. کليل سوالات / TBD

دستاويز جو اختتام۔