System Implementation
Overview
The Secure Controlled Guns and Ammunition Inventory Management System (SCGAIMS) was developed using a layered architecture designed to improve accountability, auditability, security governance, and operational efficiency in the management of controlled firearms and ammunition.
The implementation focuses on mitigating the weaknesses identified in traditional manual inventory tracking approaches by providing a centralized and auditable platform for inventory management, transaction processing, discrepancy detection, and investigation resolution.
Technology Stack
SCGAIMS was developed using modern web development technologies and cloud-based services.
| Component | Technology |
|---|---|
| Backend Framework | Django |
| API Framework | Django REST Framework |
| Database | PostgreSQL |
| Database Platform | Supabase |
| Authentication Provider | Auth0 |
| Source Control | Git |
| Repository Management | GitHub |
| DNS Management | Cloudflare |
| Documentation | Markdown / Docusaurus |
| API Testing | Postman |
Application Architecture
The implementation follows a layered architecture.
Presentation Layer
│
▼
Authentication Layer
(Auth0)
│
▼
Application Layer
(Django)
│
▼
Services Layer
(Business Logic)
│
▼
Data Layer
(PostgreSQL / Supabase)
This architecture separates business logic from data management and security controls.
Django Backend Implementation
Django serves as the primary application framework.
Primary responsibilities include:
- Request Processing
- API Endpoint Management
- Business Logic Execution
- Data Validation
- Audit Log Generation
- Investigation Processing
The backend exposes RESTful API endpoints that support inventory management workflows.
Inventory Management Implementation
Purpose
The inventory management module provides centralized management of firearms and ammunition records.
The module supports:
- Inventory visibility
- Quantity tracking
- Inventory retrieval
- Inventory updates
- Inventory accountability
Inventory Tracking
Inventory quantities are maintained within PostgreSQL and updated automatically when inventory is:
Issued
Returned
Adjusted
This ensures inventory records remain synchronized with operational activity.
Inventory Issuance Implementation
Purpose
The issuance module records the distribution of controlled assets to officers.
Workflow
Inventory Selected
|
▼
Quantity Requested
|
▼
Availability Validation
|
▼
Record Issue Transaction
|
▼
Inventory Updated
|
▼
Audit Log Created
Validation Logic
Before inventory is issued the system verifies:
- Inventory exists
- Quantity requested is valid
- Sufficient inventory remains available
If validation fails:
Transaction Rejected
Result
Successful issuance operations:
- Create Issue Records
- Update Inventory Quantities
- Generate Audit Records
Inventory Return Implementation
Purpose
The return module records the return of previously issued firearms and ammunition.
Workflow
Issue Record Selected
|
▼
Returned Quantity Entered
|
▼
Inventory Updated
|
▼
Compare Quantities
|
▼
Discrepancy Evaluation
Return Processing
The return process updates:
Inventory Quantity
Issue Record
Transaction History
before initiating discrepancy evaluation.
Discrepancy Detection Implementation
Purpose
The discrepancy engine identifies differences between:
Quantity Issued
and
Quantity Returned
This provides automated detection of potential accountability concerns.
Logic
IF
Quantity Returned
!=
Quantity Issued
THEN
Discrepancy Flag = True
Example
Issued: 120 Rounds
Returned: 100 Rounds
Result:
Discrepancy Detected
Outcome
When discrepancies occur:
- Issue Record Updated
- Discrepancy Flag Set
- Investigation Triggered
- Audit Log Generated
Investigation Management Implementation
Purpose
The investigation module provides structured workflows for resolving inventory discrepancies.
Investigation Lifecycle
Open
|
▼
Review
|
▼
Resolution
|
▼
Closed
Investigation Records
Investigations maintain:
- Investigation identifier
- Issue record association
- Status
- Resolution notes
- Historical activity
Resolution Processing
Supervisors or authorized users may:
Review Findings
Add Notes
Resolve Investigation
Close Investigation
Upon resolution:
Status Updated
Audit Log Generated
Audit Logging Implementation
Purpose
Audit logging provides accountability and traceability across all critical system activities.
Logged Events
Examples include:
Inventory Issued
Inventory Returned
Investigation Created
Investigation Resolved
Inventory Updated
Audit Information Captured
Audit records contain:
- User Identifier
- Action
- Target Record
- Timestamp
- Additional Details
Benefits
Audit logging supports:
- Accountability
- Compliance
- Investigations
- Forensic Review
- Governance Oversight
API Implementation
The backend exposes RESTful API endpoints through Django REST Framework.
Current implemented endpoints include:
GET /inventory/
POST /issue-item/
POST /return-item/
GET /issue-records/
GET /audit-logs/
POST /resolve-investigation/
These endpoints collectively support the primary operational workflows of SCGAIMS.
Database Implementation
PostgreSQL
SCGAIMS utilizes PostgreSQL hosted through Supabase.
Responsibilities
The database stores:
- Inventory Items
- Issue Records
- Investigation Records
- Audit Logs
- Shift Records
Data Integrity
Relational constraints are enforced using:
- Primary Keys
- Foreign Keys
- Referential Integrity Controls
This reduces data inconsistency and improves accountability.
Environment Variable Implementation
Purpose
Sensitive configuration values are stored outside source code.
Implemented Variables
Auth0
AUTH0_CLIENT_ID
AUTH0_CLIENT_SECRET
AUTH0_DOMAIN
AUTH0_CALLBACK_URL
Database
DB_NAME
DB_USER
DB_PASSWORD
DB_HOST
DB_PORT
Benefits
This approach improves:
- Security
- Maintainability
- DevSecOps Compliance
- Secret Management
Auth0 Integration Implementation
Purpose
Auth0 is being integrated as the centralized Identity Provider (IdP) for SCGAIMS.
Current Status
Configured:
Auth0 Tenant
SCGAIMS API
SCGAIMS Web Application
Roles
Permissions
Users
Application Callbacks
Environment Variables
Planned Integration Components
/login/
/callback/
/logout/
These endpoints will complete the authentication flow.
Git and Source Control Implementation
Git
Git is used for version control throughout development.
Benefits include:
- Change Tracking
- Rollback Capability
- Branch Management
- Collaboration
GitHub
The source code repository is managed through GitHub.
Repository:
SCGAIMS
Current Repository Capabilities
Source Control
Commit History
Documentation Storage
Future CI/CD Integration
Security Controls Implementation
The implementation incorporates multiple security controls.
Authentication
Auth0-based identity management architecture.
Authorization
Role-Based Access Control design through Auth0 roles and permissions.
Audit Logging
Continuous transaction logging for accountability.
Inventory Validation
Quantity validation prevents invalid transactions.
Investigation Workflow
Mandatory investigation of discrepancies.
Secret Management
Sensitive credentials removed from source code and stored in environment variables.
Current Implementation Status
Completed
✅ Inventory Management
✅ Inventory Retrieval API
✅ Inventory Issuance API
✅ Inventory Return API
✅ Issue Record Retrieval
✅ Audit Log Retrieval
✅ Discrepancy Detection
✅ Investigation Resolution
✅ Audit Logging
✅ PostgreSQL Integration
✅ Supabase Integration
✅ GitHub Repository
✅ Environment Variable Management
✅ Auth0 Configuration
In Progress
🔄 Auth0 Login Flow
🔄 Auth0 Callback Processing
🔄 Auth0 Logout Processing
🔄 Django Front-End Dashboard
Planned
📌 MFA Enforcement
📌 Step-Up Authentication
📌 GitHub Actions CI/CD
📌 CodeQL Scanning
📌 Dependabot Integration
📌 Multi-Armory Support
📌 Advanced Reporting
Conclusion
SCGAIMS has been implemented as a secure, database-driven inventory management platform focused on improving accountability, auditability, and security governance for controlled firearms and ammunition. Through the implementation of inventory tracking, issuance processing, return validation, discrepancy detection, investigation management, and audit logging, the system provides a structured solution that directly addresses deficiencies identified in traditional inventory management processes.