Backend Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Outmanage backend is a TypeScript-based API built using the Express.js framework, designed to manage outbound logistics operations. Its primary purpose is to handle warehouse inventory, customer delivery orders, shipment tracking, and complex weighing logic for logistics fleet management. The system employs a layered architecture that separates request handling, business logic, and database interactions through an ORM layer.
Sources: CLAUDE.md:1-20, package.json:1-40, comprehensive-swagger-api.json:1-15
Core Technology Stack
The application utilizes a modern Node.js ecosystem to ensure type safety, scalable data management, and comprehensive API documentation.
| Component | Technology | Description |
|---|---|---|
| Runtime | Node.js | Execution environment for the JavaScript/TypeScript code. |
| Framework | Express.js | Web framework for routing and middleware management. |
| Language | TypeScript | Provides static typing and modern JavaScript features. |
| Database | MySQL | Relational database for persistent storage. |
| ORM | Prisma | Object-Relational Mapper for database schema and queries. |
| Documentation | Swagger/UI | Auto-generated and comprehensive API documentation. |
| Validation | Joi | Schema description and data validation library. |
Sources: package.json:15-50, CLAUDE.md:22-30, src/index.ts:1-30
System Architecture & Data Flow
The backend follows a standard controller-service-repository pattern (where Prisma acts as the repository layer). This separation ensures that business logic is isolated from HTTP concerns and database implementation details.
Application Layer Flow
The following diagram illustrates the flow of a typical request through the system:
The system uses a centralized error middleware and logging via Winston to capture and format responses consistently.
Sources: src/index.ts:40-90, CLAUDE.md:32-60, src/controllers/reportController.ts:1-50
Data Models and Relationships
The database schema is defined in Prisma, focusing on the relationship between warehouses, inventory, and the logistics lifecycle (Orders to Shipments).
Key Entity Descriptions
- Warehouse: Central facility managing products and assigned users. Sources: prisma/schema.prisma:98-109
- Shipment: Represents a logistics movement (ANTAR or JEMPUT) involving an Armada (vehicle). Sources: prisma/schema.prisma:243-269
- DeliveryOrder: Customer-specific orders that are fulfilled through one or more shipments. Sources: prisma/schema.prisma:199-215
- Audit Logs: Comprehensive logging models (UserLog, WarehouseLog, ProductLog, etc.) track all CRUD actions with old/new data snapshots. Sources: prisma/schema.prisma:41-55, prisma/schema.prisma:111-125
Logic & Service Layer
The service layer contains the most critical business logic, specifically regarding shipment weighing and reporting.
Shipment Weighing Logic
The system supports bulk weighing where a single weighing event (Gross/Tare/Net) can be distributed across multiple shipment items associated with the same product.
- Selection: Items are marked as
CHOSEN. - Weighing: Bulk weights are recorded in
ShipmentChosenProductWeighing. - Distribution: Weights are distributed proportionally to individual
ShipmentItementries based on requested quantities. - Documentation: Generation of "Nota Timbangan" (Weighing Note) and "SPMB" (Loading Instruction) via PDFKit.
Sources: src/services/spmbPdfService.ts:1-50, src/services/notaTimbanganPdfService.ts:1-100, comprehensive-swagger-api.json:550-600
Reporting Engine
The reportService aggregates data across multiple dimensions to provide operational insights.
- Operational Reports: Aggregates shipments by type (ANTAR/JEMPUT) and status (PENDING/PROSES/SELESAI).
- Daily Output: Tracks inventory leaving the system, grouped by item, customer, or vehicle.
- Dashboard Summary: Provides high-level KPIs like completion rates and active vehicle counts.
Sources: src/services/reportService.ts:30-150, src/controllers/reportController.ts:15-60
API Infrastructure
The API is exposed via Express routes with a prefix of /api.
Security & Authentication
- Authentication: Custom JWT implementation using the
x-outmanage-tokenheader. - RBAC: Role-based access control with granular permissions (CREATE, READ, UPDATE, DELETE, WEIGH, VERIFY_PLATE, etc.).
- CORS: Restricted to specific frontend domains (Vercel, local development, and production domains).
Sources: src/index.ts:32-55, comprehensive-swagger-api.json:20-40, prisma/seed.ts:45-100
File Management
The system handles three main types of static files served via the /public route:
- Plate Photos: Uploaded images of vehicle plates for AI verification via Google Gemini.
- SPMB PDFs: Loading instruction documents.
- Nota Timbangan PDFs: Official weighing receipts.
Sources: src/services/fileService.ts:1-40, CLAUDE.md:75-85
Configuration and Deployment
The environment is configured for the Asia/Jakarta (GMT+7) timezone across all operations to ensure consistency in logistics scheduling and reporting.
// From src/index.ts:100-110
app.get('/health', (_, res) => {
const jakartaTime = new Date();
jakartaTime.setHours(jakartaTime.getHours() + 7);
res.status(200).json({
status: 'ok',
timestamp: jakartaTime.toISOString(),
});
});
Sources: src/index.ts:100-110, package.json:7-12
Summary
The Outmanage backend architecture provides a robust foundation for logistics management by integrating transactional data (Prisma/MySQL) with operational tools (AI plate verification, PDF generation) and comprehensive audit trails. The modular service-oriented design allows for complex business rules, such as proportional weight distribution, to be managed independently of the API delivery layer.