GBG-X
ENTERPRISE ERP

• Uses FastAPI lifespan management to connect to MongoDB during startup and close connections during shutdown.
• Runs index creation during application startup.
• Applies global X-GBGX-S2S middleware; /health and OPTIONS bypass the S2S check.
• Loads CORS origins from CORS_ALLOWED_ORIGINS.
• Registers the application routers under /api/v1.

• Uses Pydantic BaseSettings for typed environment configuration.
• Loads development settings from .env.
• Includes MongoDB, JWT, AWS S3, and token-expiration configuration.

• Maintains primary and optional read-replica MongoDB clients.
• Falls back to the primary database when a read replica is not configured.
• Exposes get_db() and get_read_db() as FastAPI dependencies.
• Uses lazy connection behavior to support AWS SnapStart-style serverless execution.

• create_indexes.py defines indexes for high-volume and query-sensitive collections.
• run_indexes.py applies indexes independently from the FastAPI process.
• backfill_quants.py rebuilds inventory_quants by replaying historical DONE and RESERVED stock moves chronologically.

• Standardizes Python logging with timestamp, level, logger name, and message.
• Writes to stdout for cloud logging systems.

• Writes critical actions to the audit_logs collection.
• Records action, entity type, entity ID, user email, and timestamp.
• Functions as an append-only historical audit mechanism.

• Stores pending business events in event_outbox.
• process_outbox() polls and processes pending events.
• Uses deterministic SHA-256 payload hashing and processed_events to provide idempotency.
• Routes event types through handle_event_by_type().
• Includes structural support for Idempotency-Key middleware.

• Defines EnterprisePDF branding, headers, footers, page numbers, and UTC timestamps.
• Generates purchase orders, sales invoices, GRNs, delivery challans, and packing slips.
• Supports serial-number rows, EV identifiers, payment history, and balance-due presentation.

Defines abstract interfaces for future predictive capabilities:

• StockoutPredictor — stockout probability and demand forecasting.
• VendorRiskRanker — supplier risk and delay prediction.
• BatteryDegradationAnalyzer — battery RUL and anomaly analysis.

Defines the system role hierarchy:

• bcrypt is used for password hashing and verification.
• create_access_token() signs JWT claims with JWT_SECRET_KEY.
• Access tokens receive an expiration claim based on ACCESS_TOKEN_EXPIRE_MINUTES.

• OAuth2PasswordBearer extracts the Bearer token.
• JWT validation checks the signature and required claims: sub, role, tenant_id.
• require_roles() creates route-specific RBAC dependencies.
• get_entity_filter() constructs tenant-aware MongoDB filters.
• COMPANY_ADMIN may receive an unrestricted filter; tenant-bound roles receive tenant-specific filters.

• authenticate_user() verifies identity and active status.
• login_user() issues a JWT and returns role and tenant information.
• The MongoDB user _id is used as the JWT sub claim.

• Authentication profiling logs can measure bcrypt and MongoDB execution time.

• Company administrators can provision warehouses, dealers, and vendors.
• Enforces a single CENTRAL_WAREHOUSE rule.
• Generates readable tenant IDs using WH- / DLR- prefixes and UUID-derived suffixes.
• Creates a linked admin user for a newly provisioned entity.
• Staff tenant_id is derived from the manager's JWT rather than trusted request data.
• Suspending an entity cascades is_active=False to users belonging to that tenant.

• Uses API → Domain Service → Repository layering.
• Prevents duplicate parent and variant SKUs.
• Generates variant SKUs when missing.
• Blocks product deletion when stock_moves contain inventory history.
• Cleans fitment_registry when a product is deleted.
• Supports hierarchical categories with level and hierarchy path.
• Uses strict Pydantic validation for warranty months, costs, prices, UOM, serialization type, and compliance type.
• Enforces selling_price >= cost_price.

• Validates Indian GSTIN format and normalizes phone numbers.
• Provisions vendor record, VENDOR portal account, and entities record.
• Maintains a reliability score from 0 to 100.
• QC results can adjust reliability; low scores can automatically suspend the vendor.

• Server-side PO pricing prevents client-side price tampering.
• Supports RFQs sent to multiple vendors.
• Public quote submission can be performed through a secure link.
• GRN processing supports external vendors and internal transfers.
• Serial validation and batch ID generation preserve FEFO integrity.
• Three-way invoice matching compares PO, GRN, and supplier invoice values.

Invoice states: MATCHED PRICE_DISCREPANCY GRN_MISSING

• Supports service orders, AMCs, warranties, and part swaps.
• Ticket closure uses a MongoDB transaction for coordinated inventory, warranty, defective-asset, and invoice writes.
• Serialized consumed parts require serial-number information.
• Warranty claims can move defective serialized assets to a DAMAGED zone.
• Warranty tickets can generate zero-value paid invoices and close automatically.
• Service execution integrates with EV assets for uninstall/install operations.

• Can automatically provision a CUSTOMER portal account for a newly encountered customer email.
• Creates sales orders together with SALES_ORDER_CREATED outbox events inside an ACID transaction.
• Reservation processing can occur asynchronously through the Outbox Worker.
• FEFO bin allocation computes net available stock and creates granular RESERVED moves.
• Order listing uses batch queries to avoid an N+1 stock-move lookup pattern.
• Delivery performs coordinated inventory deduction, vehicle ownership transfer, warranty registration, and invoice generation.

• Validates warranty eligibility from serial history, original receipt timing, and catalog warranty duration.
• Creates RMA records and RETURN stock moves.
• Failed parts can be moved to VIRTUAL-SCRAP-LOC and associated RMAs marked SCRAPPED.
• Return and scrap actions are auditable.

• Uploads media to AWS S3.
• Uses lazy boto3 import inside the upload endpoint.
• Protects uploads through RBAC.
• Uses UUID-based object keys to avoid filename collisions.

• StockMoveBase models source and destination locations plus serial, batch, manufacturing-date, cost, and tenant data.

Statuses: DRAFT RESERVED DONE CANCELLED

Move types: RECEIPT PICK PACK TRANSFER SCRAP PUTAWAY + related operations

• Defines a Protocol for inventory capabilities such as get_available_inventory, reserve_inventory, and process_qc.

• create_stock_move() prevents identical source and destination locations.
• Tenant IDs can be extracted from location identifiers.
• Writes immutable stock moves and synchronizes inventory_quants.
• DONE movements adjust physical availability; RESERVED movements adjust available/reserved balances.

• inventory_quants provides fast current-state stock reads.
• Uses MongoDB $inc for atomic quantity updates.
• Ignores virtual and transitional locations for active-stock calculations.
• Supports FEFO deduction behavior when manufacturing date is not directly supplied.
• Removes zeroed quant documents.

• Builds warehouse/zone/rack/bin hierarchy paths.
• Validates root locations and provides safe location resolution.
• Cycle counts use snapshot/recheck concurrency control and return 409 Conflict when stock changes during counting.
• Adjustments use virtual gain/loss locations to preserve double-entry accounting.

• Applies tenant-based filters to movement and quant queries.
• Putaway queue identifies transit stock and suitable empty bins.

• Calculates batch-level availability with MongoDB aggregation.
• Sorts batches by manufacturing date for FEFO.
• Creates RESERVED moves until requested quantity is allocated.
• Uses idempotency keys to prevent duplicate reservations.

• Builds a RESERVED pick queue while excluding PUTAWAY work.
• Validates picks and transitions moves to DONE.
• Synchronizes related PO/transfer statuses for transit-bound stock.

• Creates OPEN packages and associates picked stock moves with package IDs.
• DISPATCHED packages receive courier tracking and timestamps.
• Provides a queue of picked but unpackaged customer-bound items.

• Supports inter-location, inter-entity, and Return-to-Vendor movements.
• Uses PENDING_APPROVAL before generating RESERVED pick tasks.
• Routes RTV/RMA-related defective assets through DAMAGED zones.
• Uses bin-level FEFO allocation for standard transfers.

• Runs QC updates inside MongoDB transactions.
• Moves items to QC_PASS or QC_FAIL destinations.
• Adjusts vendor reliability based on pass/fail results.

• Refurbishment can return a recoverable item from scrap to active inventory.
• trace_serial_number() builds a chronological serialized-asset movement history and resolves human-readable locations.

• Serializes MongoDB documents for frontend consumption.
• Calculates inventory and backorder valuation using product catalog prices.
• Defaults missing prices to 0.0 for conservative metric behavior.
• Computes QC pass rate and fill rate through database-side aggregation.

• Calculates tenant-scoped inventory valuation while excluding virtual, transit, and damaged locations.
• Calculates vendor lead time and defect rates with defensive datetime checks.
• Provides simplified FIFO valuation from historical receipt and QC-pass moves.

• Uses asyncio.gather for concurrent dashboard queries.
• Provides role-specific summaries for dealers, warehouse managers, and company administrators.
• Scopes audit results for non-admin users to their tenant.

• Defines dashboard areas, risk levels, and KPI types.
• Pydantic response models such as VendorMetric and RecallReportResponse provide stable API contracts.

• install_part_to_vehicle() and uninstall_part_from_vehicle() create assembly events and update cached vehicle component serials.
• Cached fields such as current_battery_serial reduce repeated historical queries.
• mint_refurbished_part() supports serialized component refurbishment and re-entry to inventory.
• swap_vehicle_component orchestrates uninstall, install, warranty changes, RMA generation, and potential vendor debit notes.
• get_unified_product_passport accepts VIN or serial number and returns consolidated lifecycle information.

• Uses Domain Service + Repository architecture.
• Validates product existence before mapping.
• Prevents invalid VEHICLE-to-VEHICLE mappings.
• Prevents duplicate mappings at the same fitment position.
• Enriches compatibility responses with catalog information.

• Tracks State of Health and cycle count.
• Supports battery transfer between vehicles and stock.
• Synchronizes battery current_vehicle_vin and status.
• Clears the old vehicle's battery reference and sets the new vehicle's reference during transfers.