تکنیکی فن تعمیر

سندھ آئی ٹی پورٹل — سہولت ڈیسک (SITP) کا سرِ تا سر انجینئرنگ فن تعمیر: اجزاء، تہیں، ڈیٹا، اے آئی، سیکیورٹی، تعیناتی، اور عملہ۔

1. فن تعمیر کا جائزہ و اصول

SITP کو ایک API-first، ماڈیولر مونولیت کے طور پر انجینئر کیا گیا ہے جس میں پلگ ایبل اے آئی/او سی آر تہہ ہے، تعمیر کے اعتبار سے کثیر لسانی (EN/UR/Sindhi)، ہر تہہ پر کردار پر مبنی دائرہ کار، سرِ تا سر feature-flagged، اور observability-first۔ ذیل کے بنیادی اصول اس دستاویز کے ہر downstream ڈیزائن فیصلے کی حکومت کرتے ہیں۔

تعمیری اصول

یہ فن تعمیر مائیکروسروسز کے پھیلاؤ کے بجائے چند اچھی طرح سے چلائے جانے والے اجزاء کو ترجیح دیتا ہے: ایک app DB، ایک cache، ایک سرچ، ایک object store، ایک identity provider، ایک queue، ایک BI ٹول۔ یہ ٹیم کے سائز، Server4Sale پر سنگل ہوسٹنگ نقطہ آغاز، اور صوبائی حکومت کی عملی سادگی کی خواہش سے مطابقت رکھتا ہے۔ درزوں (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 کو نہیں کراس کرتے۔
• 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 کے بعد work کریں) تاکہ 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_) تاکہ ڈیٹا بیس split کیے بغیر ماڈیول ownership نظر آئے۔
• 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 کے متعدد concrete adapters ہیں۔ سروس call کے وقت فی 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 (صرف call کی 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 sنبھالا جاتا ہے (ٹکٹ 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 کو قابلِ قبول طور پر sنبھالتا ہے؛ 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 ہوتی ہے؛ file 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: ہر file اپنے 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 میں start ہو۔

12. Notifications Pipeline

pipeline ایک single domain event (مثلاً، "ticket updated") کو وصول کنندہ کی ترجیحات کے مطابق متعدد 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 کے ذریعے sنبھالا (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 se بچا جاتا ہے۔
• 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 منٹ supports۔
• RTO target: placeholder — DR runbook میں confirm ہوگا؛ current capability mariabackup restore کے ذریعے اسی ہوسٹ پر گھنٹوں میں recovery، اور off-host recovery ایک طویل window میں supports۔
• 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

دستاویز کا اختتام۔