Documentation
Project 1 - B2B SaaS platform
B2B SaaS platform for efficient customer support ticket management.
B2B SaaS platform for small businesses to manage customer support tickets. Multi-tenant with workspaces, role-based permissions (admin/agent/viewer), email-to-ticket conversion via SendGrid inbound parse, Slack/Discord notifications, SLA tracking with escalation rules, customer satisfaction surveys, and Stripe-based subscription billing with usage-based add-ons.
Overview
Project 1 is a multi-tenant B2B SaaS platform designed to streamline customer support ticket management for small businesses. It features role-based permissions, email-to-ticket conversion, and integrates with various notification services to enhance user experience. The architecture leverages microservices for scalability and maintainability, ensuring that each component can evolve independently while maintaining tenant isolation.
Architecture
Edge
API Gateway
nginx
Routes all incoming requests to the appropriate service, processing authentication and tenant-specific data before forwarding to downstream services.
Services
Auth Service
Node.js
Handles user authentication and role management, interfacing with PostgreSQL for user data and caching results in Redis.
Tenant Service
Node.js
Manages tenant-specific data and isolation, ensuring that each tenant's data is securely handled and retrieved from PostgreSQL.
Core Domain Service
Node.js
Contains the business logic for ticket management, interacting with PostgreSQL to save and retrieve ticket data.
Billing Service
Node.js
Handles subscription management and payment processing, communicating with the Stripe API for billing and logging actions in the Audit Log Service.
Notification Service
Node.js
Processes notifications for various events, sending messages through SendGrid, Twilio, and FCM, while publishing events to the Kafka Event Bus.
Audit Log Service
Node.js
Tracks changes and actions within the system, ensuring compliance and traceability of user actions.
Data
PostgreSQL
PostgreSQL
Primary data store for user, tenant, and ticket information, ensuring data integrity and isolation between tenants.
Redis Cache
Redis
Provides a caching layer for session data and frequently accessed information, reducing load on PostgreSQL.
Messaging
Kafka Event Bus
Kafka
Facilitates asynchronous event processing, allowing services to communicate without tight coupling.
External
SendGrid API
SendGrid
Handles email notifications for ticket updates and customer satisfaction surveys.
Twilio SMS Gateway
Twilio
Sends SMS notifications for urgent ticket updates.
FCM Push Service
Firebase
Delivers push notifications to mobile devices for ticket updates.
Stripe API
Stripe
Processes subscription billing and handles payment transactions.
Data Model
PostgreSQL
Flows
Customer email
Convert customer emails into support tickets.
- 1CustomerSends support email
- 2Web ClientCreates ticket request
- 3API GatewayRoutes request to Tenant Service
- 4Tenant ServiceReturns tenant data
- 5API GatewayRoutes to Core Domain Service
- 6Core Domain ServiceSaves ticket
- 7PostgreSQLConfirms ticket saved
- 8Core Domain ServiceNotifies agentasync
- 9Notification ServiceSends notificationasync
Notification to agent is asynchronous to avoid blocking ticket creation.
Agent
Resolve support tickets efficiently.
- 1AgentResolves ticket
- 2API GatewayChecks SLA
- 3Tenant ServiceGets SLA details
- 4Core Domain ServiceReturns SLA details
- 5Tenant ServiceTriggers CSAT surveyasync
- 6API GatewayIncrements billing usage
- 7Billing ServiceLogs billing increment
- 8Audit Log ServiceConfirms log entry
CSAT survey trigger is asynchronous to enhance user experience.
Integrations
Stripe
Subscription billing + webhook-driven plan updates
SendGrid
Email notifications for ticket updates
Twilio
SMS notifications for urgent updates
FCM
Push notifications for mobile updates
Tech Decisions
Why Node.js for services
Node.js provides non-blocking I/O, making it suitable for handling multiple concurrent requests efficiently.
Why Redis for caching
Redis offers high-speed access to session data, significantly improving response times for user interactions.
Why Kafka over REST
Kafka allows for asynchronous processing of events, reducing coupling between services and improving scalability.
Why PostgreSQL for data storage
PostgreSQL's support for complex queries and transactions is essential for managing multi-tenant data securely.
Why microservices architecture
Microservices allow teams to develop, deploy, and scale services independently, enhancing agility and reducing time to market.
Why this architecture
Microservices architecture
Enables independent scaling and deployment of services, enhancing maintainability.
Redis as cache layer
Improves performance with sub-ms session lookups, reducing database load.
Kafka for event processing
Decouples services, allowing for asynchronous communication and improved fault tolerance.
PostgreSQL for data storage
Provides robust data integrity and supports complex queries for tenant management.
Stripe for billing
Offers a reliable and secure payment processing solution with built-in subscription management.
Operational concerns
API Gateway is single entry point
Mitigation: Implement multiple instances behind a load balancer for redundancy.
PostgreSQL may become a bottleneck
Mitigation: Use read replicas to distribute read load and optimize performance.
Asynchronous notifications may delay user feedback
Mitigation: Ensure notification services are optimized for quick delivery.
Scale Considerations
The architecture employs Redis for caching frequently accessed data, which minimizes database load and improves response times. Asynchronous processing via Kafka allows services to handle high volumes of events without blocking, facilitating horizontal scaling. The use of microservices enables independent scaling of components based on demand, ensuring optimal resource utilization.
Generated by Skeema · 5/23/2026, 11:42:44 AM