@kudusov.takhir/ba-toolkit 1.2.0

package/skills/references/domains/healthcare.md

@@ -0,0 +1,223 @@
+# Domain Reference: Healthcare / MedTech
+
+Domain-specific knowledge for healthcare and medical technology projects: telemedicine platforms, patient portals, EHR/EMR systems, clinic management systems, mental health apps, medical device integrations, pharmacy platforms.
+
+---
+
+## 1. /brief — Project Brief
+
+### Domain-specific interview questions
+- Product type: telemedicine (video consultations), patient portal, EHR/EMR, clinic management, mental health app, pharmacy, medical IoT, health insurance tool?
+- Primary beneficiary: patients, clinicians, clinic administrators, insurance providers?
+- Geographic scope and primary jurisdiction (impacts regulatory requirements: HIPAA / GDPR / FHIR)?
+- Funding model: SaaS subscription (clinic/hospital), direct-to-consumer (D2C), insurance-funded, employer-funded?
+- Integration with existing clinical systems: EHR, LIS (lab), RIS (radiology), billing?
+
+### Typical business goals
+- Reduce patient wait times and administrative overhead.
+- Increase patient retention and adherence to treatment plans.
+- Enable remote care delivery and reduce in-person visit load.
+- Ensure regulatory compliance and pass clinical audits.
+- Provide clinicians with accurate, timely patient data at point of care.
+
+### Typical risks
+- Regulatory non-compliance (HIPAA, GDPR, MDR for medical devices) — fines and loss of licence.
+- Data breach exposing Protected Health Information (PHI) — reputational and legal damage.
+- Clinical error due to incorrect or outdated patient data — patient safety risk.
+- Integration complexity with legacy EHR systems (HL7 v2, FHIR R4).
+- Low clinician adoption due to poor UX or disruption to existing workflows.
+
+---
+
+## 2. /srs — Requirements Specification
+
+### Domain-specific interview questions
+- Roles and actors: patient, doctor/physician, nurse, specialist, pharmacist, lab technician, billing/revenue cycle, admin, insurance coordinator?
+- Appointment types: in-person, video, phone, async messaging?
+- Prescription handling: electronic prescriptions (e-Rx) sent to pharmacy, or printed?
+- Lab results: manual upload, HL7/FHIR integration with LIS, patient-facing results?
+- Billing: self-pay, insurance claims (CMS-1500, UB-04), co-pay collection at visit?
+- Consent management: digital consent forms, consent audit trail, HIPAA authorizations?
+- Multi-clinic or multi-provider support?
+
+### Typical functional areas
+- Patient registration and identity verification.
+- Appointment scheduling (booking, rescheduling, cancellation, reminders).
+- Video / async consultation module.
+- Medical records — SOAP notes, diagnosis codes (ICD-10), problem list, allergies.
+- Prescription management (e-Rx, medication history, refill requests).
+- Lab results — ordering, result delivery to patient and clinician.
+- Billing and insurance claims management.
+- Consent and legal document management.
+- Notifications — appointment reminders, result alerts, prescription ready.
+- Admin dashboard — scheduling, capacity, staff management, reporting.
+- Patient portal — appointments, records, messages, prescriptions.
+- Audit log — all PHI access events logged per HIPAA requirements.
+
+---
+
+## 3. /stories — User Stories
+
+### Domain-specific interview questions
+- Critical patient flows: appointment booking, video consultation, receiving lab results, requesting prescription refill?
+- Critical clinician flows: reviewing patient history before consultation, documenting a visit, ordering labs?
+- Sensitive flows requiring special handling: mental health disclosures, minor patients, proxy (guardian) access?
+
+### Typical epics
+- Patient Registration and Identity (onboarding, identity verification, consent).
+- Appointment Management (booking, reminders, rescheduling).
+- Consultation (video, async, in-person notes).
+- Medical Records (view, update, share).
+- Prescriptions (issue, refill, send to pharmacy).
+- Lab & Diagnostics (order, result notification, patient view).
+- Billing & Payments (insurance claim, co-pay, invoices).
+- Notifications & Alerts (appointment, results, messages).
+- Clinician Workflow (schedule, patient list, documentation).
+- Admin & Reporting (capacity, revenue, compliance reports).
+- Audit & Compliance (access log, consent records).
+
+---
+
+## 4. /usecases — Use Cases
+
+### Domain-specific interview questions
+- Exceptional flows: no-show patient, clinician technical issue during video call, lab result outside critical range (STAT alert)?
+- Emergency flows: how does the system handle a patient reporting a medical emergency during a telemedicine session?
+- Proxy access: can a parent book and view a minor's records? Guardian access for elderly patients?
+
+### Typical exceptional flows
+- Video call technical failure — fallback to phone consultation or reschedule offer.
+- Critical lab value detected — automated STAT alert to clinician, acknowledgement required.
+- Prescription cannot be sent electronically — fallback to printed/faxed prescription.
+- Patient no-show — automatic status update, slot released for rebooking.
+- Insurance claim rejected — notification to billing coordinator with rejection code and resubmission guidance.
+- Clinician cancels same-day — patient notification and priority rebooking offer.
+
+---
+
+## 5. /ac — Acceptance Criteria
+
+### Domain-specific interview questions
+- PHI access controls: role-based access, break-glass emergency access, access logging for HIPAA?
+- Consent requirements: what must be consented before each consultation type? Is re-consent required on policy changes?
+- STAT alerts: what defines a critical lab value? Who must be notified, in what timeframe, with what acknowledgement?
+- Audit trail: what events are logged (who accessed what and when)? How long are logs retained?
+- Prescription validation: formulary check, drug-drug interaction check — automatic or manual?
+
+---
+
+## 6. /nfr — Non-functional Requirements
+
+### Domain-specific interview questions
+- Regulatory jurisdiction: HIPAA (US), GDPR (EU), both, other national regulation?
+- Data residency: must PHI remain in-country (specific cloud region)?
+- Medical device classification (if applicable): FDA Class I / II, CE marking, MDR?
+- Availability expectations: 24/7 for patient-facing portal; business hours only for admin?
+
+### Mandatory NFR categories for Healthcare
+- **Security & Compliance:** HIPAA Business Associate Agreement (BAA) with all vendors storing PHI. End-to-end encryption of PHI in transit (TLS 1.2+) and at rest (AES-256). RBAC with least-privilege. MFA for clinician accounts.
+- **Audit:** All PHI access events logged immutably with user ID, timestamp, record accessed. Minimum retention 6 years (HIPAA). Logs must be tamper-evident.
+- **Availability:** Patient portal and consultation module SLA 99.9%. Admin-only functions may be 99.5%. Planned maintenance during low-usage windows only.
+- **Performance:** Appointment booking page < 1.5s. Video call connection < 5s from acceptance. Lab result page load < 2s.
+- **Data Integrity:** Clinical data must be immutable after clinician sign-off. Corrections tracked as addenda, not overwrites.
+- **Interoperability:** HL7 FHIR R4 APIs for EHR integration where applicable. ICD-10 and CPT codes must be validated against official code sets.
+- **Backup & Recovery:** PHI backups daily, retained 30 days. RTO < 4 hours, RPO < 1 hour for clinical data.
+- **Consent:** Digital consent with timestamp, version, and patient signature must be stored for the lifetime of the patient record.
+
+---
+
+## 7. /datadict — Data Dictionary
+
+### Domain-specific interview questions
+- Patient identity: how is identity verified at registration (government ID, insurance card, email only)?
+- Medical record model: SOAP notes (Subjective, Objective, Assessment, Plan)? Problem-oriented? Free text?
+- Diagnosis coding: ICD-10-CM (clinical), ICD-10-PCS (procedures), or both?
+- Multi-provider: does a patient record belong to one clinic or is it portable across providers on the platform?
+- Soft delete: are patient records soft-deleted (retention required by law)?
+
+### Mandatory entities for Healthcare
+- **Patient** — demographic: name, DOB, gender, contact, insurance, emergency contact. PHI-flagged.
+- **Clinician** — physician, nurse, specialist: NPI number, credentials, specialties, licence state.
+- **Appointment** — type, status (scheduled → confirmed → completed / cancelled / no-show), provider, patient, slot.
+- **ConsultationNote** — SOAP or structured note: subjective, objective, assessment, plan, author, signed timestamp.
+- **Diagnosis** — ICD-10 code, description, onset date, status (active, resolved), linked to note.
+- **Prescription** — medication name, dosage, frequency, quantity, refills, prescriber, date, e-Rx status.
+- **LabOrder** — test panel ordered, ordering clinician, date, priority (routine / STAT).
+- **LabResult** — test name, value, unit, reference range, abnormal flag, received date, reviewed flag.
+- **MedicationHistory** — current and past medications, source (self-reported, EHR, pharmacy).
+- **Allergy** — substance, reaction type, severity, reported date.
+- **InsurancePlan** — payer, plan name, member ID, group number, copay, deductible.
+- **Claim** — billing claim: CPT codes, ICD-10 codes, amount, payer, status, rejection code.
+- **Consent** — type, version, patient signature, timestamp, expiry.
+- **AuditLog** — user ID, action, resource type, resource ID, timestamp, IP address.
+- **Document** — referral, imaging report, external record: type, upload date, access permissions.
+
+---
+
+## 8. /apicontract — API Contract
+
+### Domain-specific interview questions
+- FHIR: are public FHIR R4 endpoints required (for patient data portability / CMS Interoperability Rule)?
+- Webhooks: real-time lab result delivery to clinician, appointment reminders trigger, claim status update?
+- Third-party: integration with telemedicine video provider (Daily.co, Twilio, Zoom Health), e-Rx network (Surescripts), pharmacy?
+
+### Typical endpoint groups
+- **Patients** — create, search, get profile, update demographics, get insurance.
+- **Appointments** — list availability, book, confirm, cancel, reschedule, get details.
+- **Consultations** — start session (video URL), create note, sign note, get notes.
+- **Prescriptions** — create, send to pharmacy, refill request, history.
+- **Lab Orders & Results** — create order, receive result (webhook), get results, acknowledge critical.
+- **Billing** — create claim, get claim status, process co-pay.
+- **Audit** — query audit log (admin only).
+- **Consent** — get latest consent version, record patient consent, get consent history.
+- **FHIR Resources** _(if applicable)_ — Patient, Appointment, Observation, MedicationRequest, DiagnosticReport (R4-compliant).
+
+---
+
+## 9. /wireframes — Wireframe Descriptions
+
+### Domain-specific interview questions
+- Key clinician screens: schedule view, patient chart, note editor, lab order and result view?
+- Key patient screens: appointment booking, health summary, prescription refill, lab result view?
+- Separate apps or unified platform for patient vs. clinician?
+- Video consultation embedded in platform or external link?
+
+### Typical screens
+- **Patient Portal — Home** — upcoming appointments, recent results, messages, quick book.
+- **Appointment Booking** — clinician search, availability calendar, type selection, confirmation.
+- **Consultation Screen** — video panel, patient summary sidebar, note editor, prescription action.
+- **Patient Health Summary** — problem list, medications, allergies, recent visits, lab results.
+- **Lab Result View** — result list, trend chart, reference range, abnormal highlight, clinician comment.
+- **Prescription Refill** — current medications, refill request button, pharmacy selection.
+- **Clinician Schedule** — day/week calendar, patient queue, appointment status management.
+- **Clinical Note Editor** — SOAP sections, ICD-10 lookup, CPT code entry, sign button.
+- **Lab Order Form** — panel selection, priority, ordering notes, STAT flag.
+- **Billing Dashboard** _(admin)_ — claims by status, revenue summary, rejection queue, reports.
+- **Audit Log View** _(admin)_ — searchable log table, export for compliance review.
+
+---
+
+## Domain Glossary
+
+| Term | Definition |
+|------|-----------|
+| PHI | Protected Health Information — any individually identifiable health data |
+| HIPAA | Health Insurance Portability and Accountability Act (US) |
+| EHR | Electronic Health Record — longitudinal patient record across providers |
+| EMR | Electronic Medical Record — record within a single practice |
+| FHIR | Fast Healthcare Interoperability Resources — HL7 standard for health data exchange |
+| HL7 | Health Level Seven — standard for clinical data messaging |
+| ICD-10 | International Classification of Diseases, 10th Revision — diagnosis codes |
+| CPT | Current Procedural Terminology — procedure and service codes |
+| NPI | National Provider Identifier — unique ID for US healthcare providers |
+| e-Rx | Electronic Prescription — digitally transmitted to pharmacy |
+| PCP | Primary Care Provider |
+| SOAP note | Structured clinical note: Subjective, Objective, Assessment, Plan |
+| STAT | Immediately urgent (from Latin statim) — highest clinical priority |
+| BAA | Business Associate Agreement — HIPAA-required contract with vendors handling PHI |
+| LIS | Laboratory Information System |
+| RIS | Radiology Information System |
+| Telemedicine | Remote delivery of clinical care via video, phone, or messaging |
+| Formulary | List of medications approved by an insurance plan |
+| Co-pay | Fixed patient payment per visit/prescription under insurance plan |
+| Deductible | Amount patient must pay out-of-pocket before insurance covers costs |

package/skills/references/domains/igaming.md

@@ -0,0 +1,183 @@
+# Domain Reference: iGaming
+
+Domain-specific knowledge for iGaming projects: online slots, sports betting, casino lobbies, operator admin panels, Telegram Mini Apps, promotional mechanics (tournaments, bonuses, wheel of fortune).
+
+---
+
+## 1. /brief — Project Brief
+
+### Domain-specific interview questions
+- Product type: online slot, sports betting, casino lobby, operator admin panel, promo mechanic, Telegram Mini App?
+- Jurisdictions and licenses: MGA (Malta Gaming Authority), Curaçao eGaming, UKGC (UK Gambling Commission), other?
+- Competitive products / references in iGaming?
+- Integrations: game aggregator, payment providers (which ones), KYC/AML service?
+
+### Typical business goals
+- Increase player retention and LTV (Lifetime Value).
+- Enter a new regulated market.
+- Replace legacy operator platform.
+- Grow GGR (Gross Gaming Revenue) through new game mechanics.
+- Increase ARPU (Average Revenue Per User) through promo mechanics.
+
+### Typical risks
+- License revocation or delay.
+- Regulatory changes in the target jurisdiction.
+- Dependency on a third-party game aggregator.
+- Fraud and bonus hunting.
+
+---
+
+## 2. /srs — Requirements Specification
+
+### Domain-specific interview questions
+- Roles: player, operator, administrator, compliance officer, marketing manager, support agent, affiliate?
+- External integrations: payment providers, game aggregator, KYC/AML service, CRM, push notifications, analytics, affiliate tracking?
+- Multi-currency: which currencies, including crypto? Exchange rate handling?
+- Regulatory requirements: responsible gambling, AML (Anti-Money Laundering), data retention per jurisdiction?
+- Business rules: bet limits, wagering requirements, cooldown periods, age verification?
+
+### Typical functional areas
+- Registration and verification (KYC).
+- Deposit and withdrawal.
+- Gameplay (lobby, game launch, bet history).
+- Bonus system (welcome bonus, free spins, cashback, tournaments).
+- Admin panel (player management, reports, settings).
+- Responsible gambling (limits, self-exclusion, Reality Check).
+
+---
+
+## 3. /stories — User Stories
+
+### Domain-specific interview questions
+- Critical user flows: registration, deposit, game session, withdrawal, bonus activation, verification?
+- Edge cases: bonus hunting, multi-accounting, payment timeouts, connection loss during a spin, limit exceeded?
+- Personas: newcomer, casual player, high roller, VIP, affiliate?
+
+### Typical epics
+- Registration and authentication.
+- Payments (deposit, withdrawal).
+- Gameplay.
+- Bonuses and promotions.
+- Profile and settings.
+- Administration.
+- Responsible gambling.
+- Reporting and analytics.
+
+---
+
+## 4. /usecases — Use Cases
+
+### Domain-specific interview questions
+- Critical alternative flows: payment timeout, KYC rejection, connection loss during spin, insufficient balance, account blocking?
+- System actors: payment provider, game aggregator, RNG service (Random Number Generator), KYC provider?
+
+### Typical exceptional flows
+- Payment provider integration failure.
+- Fraud suspicion (unusual betting pattern).
+- Responsible gambling limit exceeded.
+- Account blocked due to AML check.
+- Game aggregator unavailable.
+
+---
+
+## 5. /ac — Acceptance Criteria
+
+### Domain-specific interview questions
+- Business rules for AC: min/max bet, wagering requirements (playthrough multiplier), cooldown periods, withdrawal limits?
+- Boundary values: minimum deposit, maximum bet, session timeout, maximum win?
+- Data precision: currency — 2 decimal places, coefficients — 3 decimal places, RTP (Return to Player) — percentage with 0.01% precision?
+
+---
+
+## 6. /nfr — Non-functional Requirements
+
+### Domain-specific interview questions
+- Target CCU (Concurrent Users) and RPS (Requests Per Second)?
+- RNG: certification required (GLI, eCOGRA, BMM)? Audit?
+- Responsible gambling: limits (deposit, bet, loss, session time), self-exclusion, cooling-off, Reality Check?
+- Data retention: GDPR, jurisdiction-specific requirements?
+
+### Mandatory NFR categories for iGaming
+- **Performance:** spin response time < 200ms, lobby time-to-first-frame < 2s.
+- **Security:** TLS 1.2+, PII (Personally Identifiable Information) encryption, 2FA for admins, SQL injection and XSS protection.
+- **Compliance:** licensing requirements (MGA/UKGC/Curaçao), transaction audit, log retention 5+ years.
+- **Responsible gambling:** self-limitation tools, automatic notifications, forced breaks.
+- **RNG:** certified random number generator, independent audit.
+- **Availability:** SLA 99.95%+ for gameplay.
+
+---
+
+## 7. /datadict — Data Dictionary
+
+### Domain-specific interview questions
+- Which entities require full audit: transactions, bets, sessions, balance changes, admin actions?
+- Multi-currency: amounts in minor units (cents) or major? Store exchange rate at transaction time?
+
+### Mandatory entities for iGaming
+- **User** — player, including KYC status, verification, limits.
+- **Transaction** — financial operations (deposit, withdrawal, bonus, adjustment).
+- **Bet / Wager** — bet: amount, coefficient, result, game session link.
+- **GameSession** — game session: start, end, game, total bets/wins.
+- **Bonus** — bonus: type, status, wagering progress, expiry.
+- **AuditLog** — audit log: action, actor, timestamp, payload.
+- **Game** — game catalog: provider, RTP, volatility, status.
+- **PaymentMethod** — user payment methods.
+- **ResponsibleGamblingSettings** — limits and self-limitation settings.
+
+---
+
+## 8. /apicontract — API Contract
+
+### Domain-specific interview questions
+- Webhook contracts: payment provider callback, game aggregator events (round start/end, balance check), KYC results?
+- WebSocket: real-time balance, game events, tournament leaderboard?
+
+### Typical endpoint groups
+- Auth (registration, login, refresh, logout).
+- Users (profile, KYC, verification, limits).
+- Payments (deposit, withdrawal, transaction history).
+- Games (catalog, launch, history).
+- Bets (placement, history, details).
+- Bonuses (activation, status, cancellation).
+- Admin (player management, reports, settings).
+- Webhooks (payment callbacks, game aggregator events).
+
+---
+
+## 9. /wireframes — Wireframe Descriptions
+
+### Domain-specific interview questions
+- Key screens: lobby, game screen, profile, cashier (deposit/withdrawal), admin panel, bonus section?
+- Specific states: restricted region, pending verification, self-excluded, maintenance?
+
+### Typical screens
+- Lobby (game catalog with filters and search).
+- Game screen (iframe/canvas game + balance overlay).
+- Cashier — deposit (method selection, amount, confirmation).
+- Cashier — withdrawal (method, amount, verification status).
+- Profile (data, KYC, history, responsible gambling settings).
+- Bonuses (active, available, history).
+- Admin panel: dashboard, player management, transactions, reports.
+
+---
+
+## Domain Glossary
+
+| Term | Definition |
+|------|-----------|
+| GGR | Gross Gaming Revenue — total bets minus total wins |
+| NGR | Net Gaming Revenue — GGR minus bonuses and adjustments |
+| RTP | Return to Player — percentage returned to players over time |
+| Wagering requirements | Bonus playthrough requirements — how many times the bonus amount must be wagered |
+| KYC | Know Your Customer — identity verification procedure |
+| AML | Anti-Money Laundering — money laundering prevention |
+| MGA | Malta Gaming Authority — Maltese regulator |
+| UKGC | UK Gambling Commission — British regulator |
+| CCU | Concurrent Users — simultaneous users |
+| RNG | Random Number Generator |
+| Responsible gambling | A set of self-limitation tools for players |
+| Cooldown | Mandatory pause between actions |
+| Self-exclusion | Voluntary access block to gambling |
+| Reality Check | Periodic notification about session duration and results |
+| Freebet / Freespin | Free bet / free spin |
+| Game aggregator | Platform aggregating games from multiple providers |

package/skills/references/domains/logistics.md

@@ -0,0 +1,221 @@
+# Domain Reference: Logistics / Delivery
+
+Domain-specific knowledge for logistics and delivery projects: last-mile delivery platforms, courier management systems, freight and cargo tracking, warehouse management systems (WMS), fleet management, 3PL portals, route optimisation tools.
+
+---
+
+## 1. /brief — Project Brief
+
+### Domain-specific interview questions
+- Service type: last-mile parcel delivery, same-day courier, long-haul freight, food/grocery delivery logistics layer, reverse logistics (returns), 3PL white-label?
+- Ownership model: own fleet, gig/contractor drivers, hybrid?
+- Geographic scope: city-level, national, cross-border?
+- Order origination: e-commerce platform orders, business clients (B2B), or both?
+- Existing integrations: ERP, e-commerce platform (Shopify, Magento), carrier APIs, mapping services?
+
+### Typical business goals
+- Reduce cost-per-delivery through route optimisation and load efficiency.
+- Increase on-time delivery rate and reduce failed delivery rate.
+- Provide end-to-end real-time visibility to customers and dispatchers.
+- Scale operations without proportional headcount growth.
+- Reduce driver idle time and fuel consumption.
+
+### Typical risks
+- Driver safety and liability for contractor fleet.
+- Real-time GPS accuracy and connectivity in dead-zones.
+- Proof-of-delivery disputes — legal and operational risk.
+- Route planning failure during peak demand (e.g., holiday season).
+- Cross-border customs compliance and documentation errors.
+
+---
+
+## 2. /srs — Requirements Specification
+
+### Domain-specific interview questions
+- Actors: customer (end recipient), business client (shipper), dispatcher/operations manager, driver/courier, warehouse operator, admin, customer support?
+- Order creation: via platform UI, API integration (B2B), or both?
+- Route assignment: manual by dispatcher, auto-assigned by algorithm, or driver self-assign?
+- Delivery confirmation: signature, OTP, photo of parcel at door, QR scan?
+- Notifications: customer SMS/email on dispatch, ETA updates, failed delivery; driver push notifications?
+- Returns: return pickup scheduling, reverse logistics workflow?
+- SLA tiers: standard, express, same-day — different pricing and priority rules?
+
+### Typical functional areas
+- Order intake (manual, API, batch import).
+- Order lifecycle management (created → collected → in-transit → delivered / failed).
+- Route planning and optimisation.
+- Driver / courier management (profiles, shifts, capacity, vehicle).
+- Real-time GPS tracking and ETA calculation.
+- Proof of Delivery (POD) capture: photo, signature, OTP.
+- Customer notifications and self-service tracking page.
+- Dispatcher dashboard (live map, order queue, exceptions).
+- Returns and reverse logistics.
+- Warehouse / hub management (inbound, sorting, outbound).
+- B2B client portal (order submission, bulk upload, reporting, invoicing).
+- Reporting and analytics (delivery performance, SLA adherence, driver KPIs).
+
+---
+
+## 3. /stories — User Stories
+
+### Domain-specific interview questions
+- Driver app flows: receive assignment, navigate to pickup, confirm pickup, navigate to delivery, capture POD, report exception?
+- Dispatcher flows: assign unassigned orders, monitor live map, handle failed delivery, re-route driver?
+- Customer flows: track parcel, reschedule delivery, provide safe-place instructions, view POD?
+
+### Typical epics
+- Order Creation and Management.
+- Route Planning and Optimisation.
+- Driver Mobile App (pickup, delivery, POD).
+- Real-time Tracking (dispatcher and customer).
+- Proof of Delivery.
+- Failed Delivery and Exception Handling.
+- Notifications (customer, driver, dispatcher).
+- Returns and Reverse Logistics.
+- B2B Client Portal.
+- Reporting and Analytics.
+- Fleet and Driver Management.
+
+---
+
+## 4. /usecases — Use Cases
+
+### Domain-specific interview questions
+- Failed delivery scenarios: no answer at door, address not found, parcel damaged, customer refuses delivery?
+- Edge cases: driver app offline, GPS unavailable in building, customer OTP expired?
+- Cross-border: customs hold, import duty unpaid by recipient?
+
+### Typical exceptional flows
+- Driver cannot locate address — dispatcher intervention, customer contact attempt, re-route or return to depot.
+- Recipient not available — leave in safe place (if instructed), leave notice, reschedule, or return to depot after N attempts.
+- Parcel damaged at pickup — photo evidence captured, order flagged, shipper notified, claim initiated.
+- Driver app goes offline — last known GPS position retained, orders cached locally, sync on reconnect.
+- GPS signal lost in building — manual status update by driver, ETA paused.
+- OTP expired — dispatcher can regenerate and resend to customer.
+- Route optimisation service unavailable — fallback to manually ordered stop list.
+
+---
+
+## 5. /ac — Acceptance Criteria
+
+### Domain-specific interview questions
+- ETA accuracy: what tolerance is acceptable? What triggers an ETA recalculation?
+- POD validity: what counts as valid proof — photo only, photo + signature, OTP?
+- Failed delivery retry policy: how many attempts before return to depot? Time between attempts?
+- SLA breach: when is a delivery marked as breached? Who is notified and within what timeframe?
+- Driver tracking update frequency: how often is GPS position sent to the server?
+
+---
+
+## 6. /nfr — Non-functional Requirements
+
+### Domain-specific interview questions
+- Fleet size and concurrent drivers: how many drivers active simultaneously at peak?
+- Tracking update frequency required by customers: every 30 seconds, every minute?
+- Map provider: Google Maps Platform, HERE, Mapbox, or OpenStreetMap?
+- Offline-first driver app requirement: must work without connectivity for N minutes?
+- Data retention for POD and audit: how many months/years?
+
+### Mandatory NFR categories for Logistics
+- **Real-time Performance:** GPS position updates processed within 2s of receipt. ETA recalculations completed within 3s of position update. Customer tracking page reflects driver position within 5s.
+- **Scalability:** Dispatch and tracking infrastructure must handle peak order volume (e.g., holiday season) with ≤10% increase in latency.
+- **Offline Resilience (driver app):** Driver app must queue up to 200 actions (status updates, POD captures) offline and sync automatically on reconnect with no data loss.
+- **Availability:** Order management and dispatch: 99.9% SLA. Driver app backend: 99.95%. Customer tracking page: 99.9%.
+- **Data Integrity:** POD data (photos, signatures, OTP confirmation) is write-once immutable. Delivery status transitions must be logged with actor and timestamp.
+- **Security:** Driver identity verified before shift start. POD photos stored in private object storage, signed URLs for access. Customer PII (address, phone) masked in driver app after delivery completion.
+- **Location Accuracy:** GPS accuracy ≤ 50m for urban routing. Fallback to cell-tower location when GPS unavailable.
+- **Compliance:** Cross-border shipments must include required customs data fields. GDPR-compliant handling of recipient address data.
+
+---
+
+## 7. /datadict — Data Dictionary
+
+### Domain-specific interview questions
+- Order vs. shipment vs. parcel: does one order produce one shipment, or can it be split into multiple parcels?
+- Stop model: is a route a list of stops, and can stops have multiple orders?
+- Driver identity: employee record, contractor profile, or linked to external HR system?
+- Address: geocoded at creation time or on-demand?
+
+### Mandatory entities for Logistics
+- **Order** — delivery request: origin (pickup) address, destination address, parcel details, SLA tier, status lifecycle.
+- **Parcel** — physical item: dimensions, weight, barcode/QR, contents description.
+- **Shipment** — groups one or more orders for dispatch: assigned driver, vehicle, planned route, actual departure/arrival.
+- **Route** — planned sequence of stops: optimisation parameters, total distance, estimated duration.
+- **Stop** — single delivery or pickup point on a route: address, time window, linked orders.
+- **Driver** — profile: name, contact, licence, vehicle assignment, status (available, on-shift, off-duty).
+- **Vehicle** — type, capacity (weight and volume), licence plate, current assignment.
+- **TrackingEvent** — immutable event: type (picked-up, in-transit, delivered, failed), timestamp, GPS coordinates, actor.
+- **ProofOfDelivery** — delivery confirmation: photo URL, signature data, OTP token, recipient name, timestamp.
+- **FailedDelivery** — reason code, attempt number, next action (reschedule, return, safe-place), notes.
+- **Notification** — channel (SMS, email, push), type (dispatch, ETA, delivered), status (sent, delivered, failed).
+- **Hub / Depot** — warehouse or sorting hub: address, capacity, working hours.
+- **BusinessClient** — B2B shipper account: SLA agreement, billing, API credentials.
+- **Invoice** — billing to B2B client: billing period, order count, amount, payment status.
+
+---
+
+## 8. /apicontract — API Contract
+
+### Domain-specific interview questions
+- Public tracking API: unauthenticated customer tracking by tracking number?
+- Webhook needs: delivery status updates to B2B client systems, failed delivery alert to shipper?
+- Driver app API: REST or more efficient protocol (GraphQL, gRPC) for frequent GPS polling?
+
+### Typical endpoint groups
+- **Orders** — create, list, get detail, cancel, update SLA tier.
+- **Tracking** — get current status by tracking number (public, unauthenticated), get full event history.
+- **Routes** — create optimised route, get route detail, update stop sequence.
+- **Driver App** — get assigned route, confirm pickup, update stop status, submit POD, report exception.
+- **GPS** — ingest position update (high-frequency, lightweight endpoint).
+- **Dispatch** — list unassigned orders, assign to driver, reassign, dispatcher override.
+- **Notifications** — trigger manual notification, get notification history.
+- **Returns** — create return request, schedule pickup, get return status.
+- **B2B Client Portal** — submit orders (single/bulk), get order statuses, download invoice, API key management.
+- **Admin** — driver management, vehicle management, hub management, reports.
+- **Webhooks** — delivery status change, failed delivery, POD captured, SLA breach.
+
+---
+
+## 9. /wireframes — Wireframe Descriptions
+
+### Domain-specific interview questions
+- Dispatcher screen: live map as primary view, or table/queue view with map as secondary?
+- Driver app: mobile-native (iOS/Android) or mobile web (PWA)?
+- Customer tracking: standalone tracking page or embedded in shipper's website?
+
+### Typical screens
+- **Dispatcher Dashboard — Live Map** — real-time driver positions, order pins, status legend, exception alerts.
+- **Order Queue** — list of all active orders: status, driver, ETA, SLA indicator, filter/search.
+- **Order Detail (Dispatcher)** — full order timeline, current driver location, contact driver, reassign action.
+- **Route View** — ordered stop list, ETA per stop, map route overlay, capacity utilisation.
+- **Driver App — Active Route** — current stop detail, navigation action (deep link to maps), stop list.
+- **Driver App — Stop Detail** — recipient name, address, instructions, delivery action buttons (delivered, exception).
+- **Driver App — POD Capture** — photo capture, signature pad, OTP input, submit.
+- **Driver App — Exception Report** — reason selector, notes, photo, save and proceed.
+- **Customer Tracking Page** — order status, driver position on map, ETA, delivery instructions input.
+- **B2B Client Portal — Order Submission** — single order form or bulk CSV upload, SLA selector.
+- **B2B Client Portal — Reporting** — delivery performance, SLA adherence, failed deliveries, invoice download.
+
+---
+
+## Domain Glossary
+
+| Term | Definition |
+|------|-----------|
+| POD | Proof of Delivery — evidence that delivery was completed (photo, signature, OTP) |
+| Last-mile | Final leg of delivery from depot/hub to recipient's address |
+| ETA | Estimated Time of Arrival |
+| 3PL | Third-Party Logistics — outsourced logistics and fulfillment |
+| AWB | Air Waybill — shipping document for air freight |
+| Manifesto | List of shipments assigned to a vehicle or route for a given trip |
+| Depot | Distribution centre or hub where parcels are sorted and loaded |
+| SLA | Service Level Agreement — contracted delivery timeframe |
+| Dwell time | Time a driver spends at a stop — indicator of stop efficiency |
+| Geocoding | Converting a text address to geographic coordinates (lat/lon) |
+| Geofencing | Triggering an event when a device enters or exits a defined geographic area |
+| Route optimisation | Algorithm to minimise total distance/time for a set of stops |
+| Reverse logistics | Logistics flow from customer back to seller or depot (returns) |
+| Dead zone | Area with no cellular or GPS signal coverage |
+| OTP | One-Time Password — numeric code used to confirm identity at delivery |
+| Capacity | Vehicle load limit (weight in kg, volume in m³) |
+| Safe place | Pre-authorised location where parcel can be left without signature |