Skip to main content

Architecture Overview

The BOSS Platform (Business Operations & Systems Support) is a comprehensive enterprise workflow management system built with modern technologies and designed for scalability, security, and extensibility.

System Architecture​

Technology Stack​

Frontend​

  • Framework: Next.js 15.5 with React 19
  • Language: TypeScript 5
  • State Management: Zustand with persistence
  • UI Components: Radix UI primitives + Tailwind CSS
  • Data Visualization: Recharts, ReactFlow for workflow builder
  • Forms: React Hook Form with Zod validation
  • HTTP Client: Axios with interceptors
  • Real-time: WebSocket client for live updates

Backend​

  • Language: Go 1.21+
  • Web Framework: Gin for HTTP routing
  • Database: MongoDB with official Go driver
  • Caching: Redis for sessions and temporary data
  • Authentication: JWT with RS256 signing + OTP support
  • Logging: Uber Zap structured logging
  • Validation: Go validator for request validation

Database​

  • Primary: MongoDB 6.0+
    • Document-based flexible schema
    • Efficient indexing for hierarchical queries
    • Aggregation pipeline for analytics
    • GridFS for file storage
  • Cache: Redis 7.0+
    • Session storage
    • OTP management
    • API response caching
    • Real-time pub/sub

Infrastructure​

  • Deployment: Docker containers on Azure
  • CI/CD: GitHub Actions
  • Monitoring: Application Insights
  • File Storage: Azure Blob Storage (planned)

Frontend Architecture​

Component Hierarchy​

State Management Architecture​

Backend Architecture (Go)​

Layered Architecture​

Request Flow​

Database Schema (MongoDB)​

Core Collections​

Security Architecture​

Multi-Layer Security​

Role Hierarchy​

Key Features​

1. Hierarchical RBAC System​

  • 5-level role hierarchy: SUPER_ADMIN → CEO → DEPARTMENT_HEAD → MANAGER → IC
  • Granular permissions: Resource-based with actions (create, read, update, delete)
  • Scoped access: Global, Organization, Department, Team, Resource levels
  • Hierarchical visibility: Users can only see subordinates in hierarchy

2. Department & Team Management​

  • Multi-level departments: Hierarchical department structure
  • Department functions: Predefined functions (Sales, HR, Engineering, etc.)
  • Teams: Sub-units within departments with capacity management
  • Settings: Working hours, escalation policies, automation rules

3. Process Builder & Workflows​

  • Visual workflow designer: React Flow-based drag-and-drop builder
  • DAG validation: Ensures acyclic process flows
  • Task definitions: Reusable task templates with tool bindings
  • Custom fields: Dynamic fields per process/ticket
  • Phase management: Multi-phase workflow support

4. Tool Execution Framework​

  • Built-in tools: Email, WhatsApp, Apollo.io, CSV Processor, Deep Research
  • Tool templates: Smart field mapping suggestions
  • Permission system: Fine-grained tool access control
  • Output processing: Structured output visualization
  • Field mapping: Auto-map ticket fields to tool parameters

5. Communication Integrations​

  • WhatsApp: Gallabox integration with template support, session management
  • Email: SMTP-based sending with template presets
  • Message tracking: Delivery status, read receipts, cost tracking

6. Blog & CMS System​

  • Rich content: Markdown-based blog posts
  • Engagement: Likes, bookmarks, comments with nested replies
  • SEO: Meta tags, slugs, featured images
  • Analytics: View counts, interaction tracking

Extended Capabilities​

Automation & Agent Runtime​

  • Runtime Agent Service (internal/service/runtime_agent_service.go) proxies to the Python agent API, retries transient failures, and falls back to baked-in metadata when the runtime is unreachable.
  • Agent Service (internal/service/agent_service.go) persists agent definitions/runs, exposes admin CRUD, and streams run state to listeners (e.g., task/ticket automation hooks).
  • Sales Outreach Automation (internal/service/sales_outreach_service.go) reacts to ticket/task events, builds metadata packages, and fans out to the sales-outreach runtime agent.
  • Summarization & Monitoring Dispatchers (internal/service/summarization_agent_dispatcher.go, task_monitoring_agent_dispatcher.go) consume webhook events and update tickets/tasks with AI summaries, alerts, and activity timeline entries.
  • Agent Bridge (internal/api/handlers/agent_bridge_handler.go) allows external LangGraph workflows to start deep research runs or dispatch communications securely using the same tool executor, templates, and RBAC logic as the GUI.

Communications & Outreach​

  • WhatsApp Stack – internal/service/gallabox_service.go, whatsapp_session_manager.go, and related handlers manage Gallabox webhooks, sessions, cost tracking, template/preset catalogs, and timeline summaries.
  • Email Stack – Password reset + OTP flows, contact notifications, long-running conversation threads, template presets, and AI summaries live inside internal/service/email_service.go, email_template_service.go, and email_summary_service.go.
  • Voice + Streaming – internal/service/plivo_service.go orchestrates Plivo calls, WebSocket audio streaming (internal/service/websocket_manager.go), Azure transcription, and call analytics/summaries.
  • Scheduler & Google Calendar – internal/service/scheduler enforces conflict detection, participant management, and Meet link provisioning while internal/service/integration/google_calendar_service.go handles OAuth, encryption, and token refresh.

Campaigns, Contacts & Lead Systems​

  • Public capture – /api/v1/public/contacts + ContactHandler route marketing forms into Mongo and send notification emails immediately.
  • Campaign builder – internal/service/campaign_service.go constructs UTM-tagged destinations, issues branded short links (link_shortener_client.go), and generates QR codes for offline touch points.
  • Campaign analytics – /api/v1/public/campaigns/traffic records impressions/clicks that marketing automations can replay later.
  • Deep Research templates – Process-scoped templates (handled by internal/service/deep_research_template_service.go) instruct human + agent researchers how each workflow expects insights to be structured.

Cost & Intelligence​

  • Tool cost ledger – internal/service/tool_cost_service.go + cost_rate_service.go capture LLM token usage, additional components (API calls, telephony minutes), and normalize costs per tool/provider.
  • Cost dashboards – internal/service/cost_insights_service.go aggregates spend per organization/department/team/user with scope-aware APIs exposed through /api/v1/cost/dashboard.
  • Tool outputs & research history – internal/service/tool_output_service.go normalizes raw tool payloads, exposes deep research history per task, and feeds analytics dashboards.
  • Knowledge artefacts – Blog handlers with interactions/comments and summary template services ensure each department controls how AI outputs, documentation, and CMS content are produced.

Scalability Considerations​

Horizontal Scaling​

  • Stateless API: All state in MongoDB/Redis
  • Load balancing: Multiple Go API instances
  • Session management: Redis-based distributed sessions
  • Database sharding: Ready for multi-tenant sharding

Performance Optimization​

  • Redis caching: Aggressive caching strategy
  • Database indexes: Optimized for common queries
  • Connection pooling: Efficient database connections
  • Lazy loading: Frontend code splitting

Monitoring & Observability​

  • Structured logging: Uber Zap with correlation IDs
  • Audit trails: All mutations logged with user context
  • Error tracking: Comprehensive error handling
  • Performance metrics: Request timing, DB query performance

Deployment Architecture​

Next Steps​