# MAGNUM ERP # API Design Specification **Project:** MAGNUM ERP – Engineering Operations Platform **Company:** MAGNUM ENGINEERING **Framework:** FastAPI **Version:** 1.0 **Status:** Design Phase --- # Purpose This document defines the REST API architecture used by MAGNUM ERP. The API provides communication between the web interface, business logic, database, and future mobile applications. All business operations will be performed through authenticated API endpoints. --- # API Architecture ```text Browser (HTML / JavaScript) │ ▼ FastAPI Routers │ ▼ Business Services │ ▼ SQLAlchemy Models │ ▼ PostgreSQL Database ``` --- # API Standards Base URL ``` /api/v1/ ``` Response Format ```json { "success": true, "message": "", "data": {} } ``` Error Format ```json { "success": false, "message": "Customer not found" } ``` HTTP Methods GET Retrieve information POST Create new information PUT Update existing information DELETE Delete information PATCH Partial update --- # Authentication ## Login POST ``` /api/v1/auth/login ``` Request ```json { "username":"admin", "password":"********" } ``` Response ```json { "token":"JWT_TOKEN", "user":"Administrator" } ``` --- ## Logout POST ``` /api/v1/auth/logout ``` --- ## Current User GET ``` /api/v1/auth/me ``` --- # Users GET ``` /api/v1/users ``` List all users. GET ``` /api/v1/users/{id} ``` Single user. POST ``` /api/v1/users ``` Create user. PUT ``` /api/v1/users/{id} ``` Update user. DELETE ``` /api/v1/users/{id} ``` Deactivate user. --- # Customers GET ``` /api/v1/customers ``` List customers. GET ``` /api/v1/customers/{id} ``` Customer details. POST ``` /api/v1/customers ``` Create customer. PUT ``` /api/v1/customers/{id} ``` Update customer. DELETE ``` /api/v1/customers/{id} ``` Archive customer. Search GET ``` /api/v1/customers/search ``` --- # Contacts GET ``` /api/v1/contacts ``` POST ``` /api/v1/contacts ``` PUT ``` /api/v1/contacts/{id} ``` DELETE ``` /api/v1/contacts/{id} ``` --- # Enquiries GET ``` /api/v1/enquiries ``` Create POST ``` /api/v1/enquiries ``` Update PUT ``` /api/v1/enquiries/{id} ``` Assign Estimator POST ``` /api/v1/enquiries/{id}/assign ``` Close Enquiry POST ``` /api/v1/enquiries/{id}/close ``` --- # Tasks GET ``` /api/v1/tasks ``` Create Task POST ``` /api/v1/tasks ``` Update Task PUT ``` /api/v1/tasks/{id} ``` Complete Task POST ``` /api/v1/tasks/{id}/complete ``` Assign Task POST ``` /api/v1/tasks/{id}/assign ``` --- # BOQ GET ``` /api/v1/boqs ``` Create BOQ POST ``` /api/v1/boqs ``` BOQ Items GET ``` /api/v1/boqs/{id}/items ``` Add Item POST ``` /api/v1/boqs/{id}/items ``` Update Item PUT ``` /api/v1/boqs/{id}/items/{item_id} ``` Delete Item DELETE ``` /api/v1/boqs/{id}/items/{item_id} ``` --- # Estimating GET ``` /api/v1/estimates ``` Calculate Estimate POST ``` /api/v1/estimates/calculate ``` Approve Estimate POST ``` /api/v1/estimates/{id}/approve ``` --- # Quotations Create POST ``` /api/v1/quotations ``` Generate PDF POST ``` /api/v1/quotations/{id}/pdf ``` Approve POST ``` /api/v1/quotations/{id}/approve ``` Email Customer POST ``` /api/v1/quotations/{id}/email ``` --- # Projects GET ``` /api/v1/projects ``` Create POST ``` /api/v1/projects ``` Project Dashboard GET ``` /api/v1/projects/{id} ``` Project Tasks GET ``` /api/v1/projects/{id}/tasks ``` Project Documents GET ``` /api/v1/projects/{id}/documents ``` --- # Purchasing Suppliers ``` GET /api/v1/suppliers POST /api/v1/suppliers ``` Purchase Orders ``` GET /api/v1/purchase-orders POST /api/v1/purchase-orders ``` Deliveries ``` GET /api/v1/deliveries POST /api/v1/deliveries ``` --- # Dashboard Technical Dashboard ``` GET /api/v1/dashboard ``` Returns * Active enquiries * Open quotations * BOQs in progress * Tasks due today * Active projects * Purchase orders awaiting delivery --- # Documents Upload ``` POST /api/v1/documents ``` Download ``` GET /api/v1/documents/{id} ``` Delete ``` DELETE /api/v1/documents/{id} ``` --- # Reports Project Report ``` GET /api/v1/reports/projects ``` Quotation Report ``` GET /api/v1/reports/quotations ``` Profit Report ``` GET /api/v1/reports/profit ``` KPI Dashboard ``` GET /api/v1/reports/dashboard ``` --- # Security Standards * JWT authentication * Password hashing using bcrypt * Role-based permissions * HTTPS in production * Audit logging for all changes * Input validation using Pydantic * CSRF protection where applicable * Parameterised database queries through SQLAlchemy --- # API Versioning Current Version ``` v1 ``` Future versions will be released without breaking existing clients. Example ``` /api/v1/ /api/v2/ ``` --- # Development Guidelines * One FastAPI router per module. * One service layer per module. * One SQLAlchemy model per table. * Pydantic schemas for all requests and responses. * Business logic must reside in services, not in routers. * All endpoints require authentication except the login route. * Every endpoint should include validation, logging, and error handling. ``` ```