BMH Digital Systems
Forge Workspace
BMH Forge Console
Project Bible
Execution-grade system design and delivery specification.
Project Overview
Context
Project: Dealership Sales System
Company: Middelburg Auto Group
Objective: Build a centralized dealership sales and lead management system that improves lead tracking, customer follow-up, sales visibility and operational efficiency.
Problem: poor lead tracking, missed follow-ups, no central visibility of customer status, manual reporting, fragmented communication across staff, slow response to enquiries
Delivery Classification
Tier: enterprise
Priority: high
Solution Architecture
Core Design
Type: Single-platform operational system
Platforms: WebApp
Architecture: Modular operational platform with clear separation between access control, workflow logic, reporting, integrations, and future automation capability.
Users: Dealer Principal, Sales Manager, Sales Executive, Finance Admin, Reception/Admin
Strategic Notes
- Real-time capability is an important part of the solution.
- AI-related features introduce higher delivery and planning complexity.
- Compliance and responsible data handling must be built into the solution.
Scope Definition
MVP Scope
- Authentication and role-based access
- Core operational workflow management
- Priority integrations
- Essential reporting and visibility
- Real-time status visibility
Phase 2 Scope
- Advanced automation workflows
- Enhanced analytics and reporting
- Operational optimization features
- Scalable expansion modules
- AI-assisted features and intelligent decision support
Exclusions
- Non-essential third-party modules
- Advanced AI capability beyond approved scope
- Broader ecosystem expansion not required for MVP launch
Assumptions
- Client will provide access to integration documentation, credentials, and decision-makers on time.
- Business stakeholders will review and approve key delivery checkpoints without major delay.
- Phase 1 will prioritize launch-critical functionality over secondary optimization features.
Functional Modules
Authentication and Access Control
Purpose: Control secure access to the platform based on user role and responsibility.
Features:
- User sign-in
- Role-based permissions
- Protected views and actions
- Session handling
Dependencies:
- User model
- Permissions logic
Implementation Notes:
- Design access rules in a centralized and reusable way.
- Keep permission logic flexible enough for future role expansion.
- Ensure access restrictions are enforced both in UI and backend operations.
Core Workflow Management
Purpose: Support the day-to-day operational workflow the client depends on most.
Features:
- Create records
- Update statuses
- Track progress
- Assign responsibility
- Monitor operational flow
Dependencies:
- Core data entities
- Role permissions
Implementation Notes:
- This is the primary MVP delivery area and should remain focused.
- Status logic should be extensible so reporting and automation can build on it later.
- Avoid overcomplicating the first release with edge-case workflow branches.
Reporting and Visibility
Purpose: Provide operational visibility for managers, decision-makers, and internal teams.
Features:
- Summary views
- Status visibility
- Basic operational reporting
- Priority dashboards
Dependencies:
- Core workflow data
- Role permissions
Implementation Notes:
- Focus first on decision-critical visibility rather than advanced analytics.
- Design reporting outputs so they can later expand into deeper dashboards.
Integrations Layer
Purpose: Connect the platform to required third-party systems and external services.
Features:
- Dealer Principal
- Sales Manager
- Sales Executive
- Finance Admin
- Reception/Admin
Dependencies:
- API credentials
- Integration-specific workflows
Implementation Notes:
- Build integrations in an isolated and maintainable structure.
- Validate external dependencies early in the project lifecycle.
- Log integration failures and design retry/error handling intentionally.
Automation Layer
Purpose: Reduce manual effort and enforce consistency in repeatable workflow actions.
Features:
- lead capture
- enquiry routing
- follow-up reminders
- customer notifications
- finance handover alerts
- manager visibility updates
- task assignment
- basic reporting summaries
Dependencies:
- Workflow triggers
- Business rules
- Notification or job execution layer
Implementation Notes:
- Prioritize practical automations that reduce operational friction quickly.
- Treat non-essential automation as a Phase 2 enhancement when appropriate.
Roles, Data, and Integrations
Roles and Permissions
Dealer Principal
Dealer Principal role within the operational platform.
- Access dealer principal-appropriate views
- Perform dealer principal-appropriate workflow actions
- Interact with records and data relevant to dealer principal responsibilities
Sales Manager
Sales Manager role within the operational platform.
- Access sales manager-appropriate views
- Perform sales manager-appropriate workflow actions
- Interact with records and data relevant to sales manager responsibilities
Sales Executive
Sales Executive role within the operational platform.
- Access sales executive-appropriate views
- Perform sales executive-appropriate workflow actions
- Interact with records and data relevant to sales executive responsibilities
Finance Admin
Finance Admin role within the operational platform.
- Access finance admin-appropriate views
- Perform finance admin-appropriate workflow actions
- Interact with records and data relevant to finance admin responsibilities
Reception/Admin
Reception/Admin role within the operational platform.
- Access reception/admin-appropriate views
- Perform reception/admin-appropriate workflow actions
- Interact with records and data relevant to reception/admin responsibilities
Data Model Guidance
Core Entities:
- User — Represents a platform user with a defined role and access level.
- Workflow Item — Represents the main operational record or task being tracked through the system.
- Integration Event — Stores interaction history and sync activity with external systems.
Real-Time Requirements:
- WhatsApp API
- email notifications
- finance application workflow
- stock management import
Storage Requirements:
- Secure storage for core system records
- Structured storage for workflow history and status changes
- Attachment or document storage if operational workflow requires uploaded files
Integration Requirements
- Dealer Principal: Support required business capability via Dealer Principal.
- Sales Manager: Support required business capability via Sales Manager.
- Sales Executive: Support required business capability via Sales Executive.
- Finance Admin: Support required business capability via Finance Admin.
- Reception/Admin: Support required business capability via Reception/Admin.
Automation and Implementation Sequence
Automation Requirements
- lead capture: lead capture
- enquiry routing: enquiry routing
- follow-up reminders: follow-up reminders
- customer notifications: customer notifications
- finance handover alerts: finance handover alerts
- manager visibility updates: manager visibility updates
- task assignment: task assignment
- basic reporting summaries: basic reporting summaries
Implementation Sequence
- Step 1: Project setup and environment configuration — Establish repository, environments, conventions, and technical foundations.
- Step 2: Authentication and permissions foundation — Implement secure sign-in and role-based access control.
- Step 3: Core data and workflow structures — Build the main entities and workflow logic needed for MVP delivery.
- Step 4: Reporting and visibility layer — Add the priority views and outputs required for operational visibility.
- Step 5: Integration implementation — Connect required external services and validate reliable data flow.
- Step 6: Automation implementation — Introduce approved automation workflows and validate trigger accuracy.
- Step 7: QA, staging, and deployment readiness — Validate the build, test critical flows, and prepare release to production.
QA, Deployment, and Post-Launch Guidance
QA Checklist
Authentication and Access
- Users can only access the views appropriate to their role.
- Unauthorized actions are correctly blocked.
- Protected routes and backend operations enforce access consistently.
Core Workflow
- Workflow items can be created correctly.
- Status changes reflect accurately across the system.
- Assigned ownership and task progression behave as expected.
Reporting and Visibility
- Summary views show correct operational data.
- Critical reporting outputs reflect live or latest available state accurately.
Integrations
- External service connections succeed reliably.
- Integration failures are logged and handled safely.
- Data mapping is correct and verified.
Deployment Checklist
- Confirm environment variables are configured correctly
- Run all database migrations successfully
- Verify integration credentials and access levels
- Confirm storage configuration
- Enable monitoring and logging
- Verify backup and rollback readiness
- Validate production deployment checklist before release
Post-Launch Guidance
Support Recommendations:
- Provide structured support during the initial adoption period.
- Monitor user adoption, workflow friction, and support trends closely after launch.
Monitoring Recommendations:
- Track workflow errors, failed integrations, and performance issues.
- Review reporting accuracy and response times regularly.
- Monitor areas of manual fallback or process breakdown for future optimization.
Scale Considerations:
- Prepare for more users, records, and operational volume over time.
- Design key workflows so additional modules can be introduced without major rework.
Phase 2 Triggers:
- Stable MVP adoption across the client team
- Confirmed value from workflow visibility and operational control improvements
- Demand for deeper automation, reporting, and optimization capability