A comprehensive architectural overview of the Bidancer Core Backend system, showcasing microservices design, domain-driven architecture, event-driven communication, and modern development practices.
🏗️ High-Level Architecture#
The Bidancer platform follows a microservices architecture pattern with clear separation of concerns and domain-driven design (DDD) principles. Our architecture is designed for scalability, maintainability, and independent service deployment.📊 Architecture Layers#
Our system is organized into five distinct layers, each with specific responsibilities:1️⃣ Client Layer#
🌐 Web and mobile applications
🔌 Consumes APIs through the gateway layer
🎨 Handles user interactions and presentation logic
2️⃣ Gateway Layer#
Nginx: HTTPS reverse proxy for local development with wildcard SSL
API Gateway/Proxy: Intelligent request routing to appropriate microservices
🔒 Handles SSL termination, load balancing, and centralized request routing
3️⃣ Microservices Layer#
Independent, deployable services with specific business responsibilities:| Service | Responsibility |
|---|
| 🔐 Auth Service | User authentication, authorization, session management |
| 👤 User Service | User profile management and user-related operations |
| 🏢 Business Service | Business entity creation, management, and validation |
| 📋 Tender Service | Tender lifecycle management, bidding processes |
| 💬 Enquiry Service | Customer and business enquiry handling |
| 📦 Catalog Service | Product and service catalog management |
| 💰 Wallet Service | Digital wallet operations, balance management |
| 💳 Billing Service | Payment processing, invoice generation |
| 📊 Master Service | Master data and configuration management |
| 📈 Activity Service | User activity tracking and analytics |
| ⚡ Handler Service | Centralized event processing and workflow orchestration |
| 🚫 NotFound Service | Handles 404 errors and routing fallbacks |
4️⃣ Data Layer#
Domain-driven database separation using Prisma ORM:| Database | Purpose | Services |
|---|
| 🔑 Authentication DB | User credentials, sessions, tokens | Auth, User |
| 🏛️ Platform DB | Core business data | Business, Tender, Enquiry, Catalog, Activity |
| 📚 Master DB | Configuration and master data | Master |
| 💵 Wallet DB | Financial transactions and balances | Wallet, Billing |
5️⃣ Shared Libraries Layer#
Reusable components across microservices:⚙️ Config: Centralized configuration management
🛡️ Middleware: Common middleware (auth, logging, error handling)
📨 Events: Event definitions and pub/sub utilities
📧 Email: Email sending and templating
🆔 KYC Kit: KYC verification utilities
💳 Payment Gateway: Payment provider integrations
📊 Telemetry: Observability, metrics, and tracing
🔧 Utils: Common utility functions
🗄️ Database Architecture#
Domain-Driven Database Design#
Domain-Driven Database Design#
The system uses a domain-driven database design approach, with separate databases for each major domain to ensure:✅ Data isolation: Reduces coupling between services
✅ Independent scaling: Each domain can be scaled independently
✅ Focused schema management: Easier to maintain and evolve schemas
✅ Security boundaries: Better access control and data protection
📚 Database Domains#
🔑 Authentication Domain#
Schema: prisma-authentication👥 User accounts and credentials
🎫 Authentication tokens (JWT, refresh tokens)
🛡️ Two-factor authentication data
🏛️ Platform Domain#
🏢 Business entities and profiles
📋 Tender listings and bids
📦 Product/service catalog
📚 Master Data Domain#
🏷️ Categories and taxonomies
🌍 Geographic data (countries, states, cities)
🏭 Industry classifications
💵 Wallet Domain#
💰 Wallet accounts and balances
📡 Event-Driven Communication#
The system implements an event-driven architecture using Google Cloud Pub/Sub for asynchronous communication between microservices, enabling loose coupling and better scalability.📨 Event Types#
👤 User Events#
🏢 Business Events#
📝 Business profile updated
📊 Business subscription changed
📋 Tender Events#
✅/❌ Bid accepted/rejected
💬 Enquiry Events#
💰 Wallet Events#
💳 Payment Events#
✨ Benefits of Event-Driven Architecture with GCP Pub/Sub#
1.
🔗 Loose Coupling: Services don't need to know about each other directly
2.
📈 Scalability: Event consumers can be scaled independently; Pub/Sub auto-scales
3.
🔄 Reliability: Messages are persisted and delivered with at-least-once guarantee
4.
📋 Auditability: Complete event history for compliance and debugging
5.
🎯 Flexibility: Easy to add new event consumers without modifying publishers
6.
⚡ Performance: Low-latency message delivery with global infrastructure
7.
🔒 Security: Built-in encryption, IAM integration, and access controls
8.
🔁 Dead Letter Queue: Automatic handling of failed message processing
⚡ Event Processing Flow#
The Handler Service acts as a workflow orchestrator using GCP Pub/Sub. For detailed information on how the Handler Service orchestrates HTTP API calls across microservices, see the Handler Service Orchestration section below.1.
📨 Services publish events to Pub/Sub topics using @libs/events wrapper
2.
📡 GCP Pub/Sub receives and stores messages in topics
3.
🔔 Pub/Sub pushes messages to subscriptions (push) or consumers pull messages
4.
👂 Event consumers (Handler Service, Activity Service, etc.) receive messages
5.
⚡ Handler Service processes events and orchestrates workflows via HTTP API calls
6.
✅ Consumers acknowledge messages after successful processing
7.
🔁 Failed messages are retried or sent to dead letter queue
💡 Note: This pattern enables complex business workflows while maintaining loose coupling between services. GCP Pub/Sub ensures reliable message delivery with automatic retries and dead letter handling.
🎭 Handler Service Orchestration#
The Handler Service acts as the central orchestrator, processing events and coordinating actions across multiple microservices through HTTP API calls.🔄 Orchestration Workflow#
Handler Service listens to all events from the Event Bus
Events are queued and processed asynchronously
Each event contains metadata and instructions for processing
Workflow Engine analyzes the event type and data
Determines which services need to be called
Sequences API calls based on dependencies and business rules
Makes RESTful API calls to target microservices
Passes relevant data and context from the event
Handles authentication and authorization tokens
Collects responses from all API calls
Handles errors and retries failed calls
Logs results for audit and debugging
Triggers follow-up events if needed
Notifies monitoring systems
📋 Example Orchestration Scenarios#
Scenario 1: New User Registration
1.
POST /api/users/profile → Create user profile
2.
POST /api/wallet/create → Create user wallet
3.
POST /api/activity/log → Log registration activity
4.
POST /api/email/send → Send welcome email
Scenario 2: Tender Published
1.
POST /api/business/notify → Notify business owner
2.
POST /api/users/notify-matching → Notify users with matching interests
3.
POST /api/activity/log → Log tender publication
4.
POST /api/email/send-batch → Send email notifications
5.
POST /api/catalog/update-stats → Update catalog statistics
Scenario 3: Payment Successful
Event: payment.successful1.
POST /api/wallet/credit → Credit wallet balance
2.
POST /api/billing/update-invoice → Mark invoice as paid
3.
POST /api/tender/unlock → Unlock tender access if applicable
4.
POST /api/activity/log → Log payment activity
5.
POST /api/email/send-receipt → Send payment receipt
💻 Local Development Setup#
The local development environment is designed for easy setup and realistic HTTPS testing with trusted certificates.🛠️ Local Setup Components#
1️⃣ mkcert#
🔐 Generates locally-trusted TLS certificates
🏛️ Creates a local Certificate Authority (CA)
✅ Installs CA in system trust store
🌐 Supports wildcard certificates for *.local.bidancer.com
2️⃣ dnsmasq#
🔍 Provides wildcard DNS resolution
🎯 Routes all *.local.bidancer.com to 127.0.0.1
🚫 Eliminates need for manual /etc/hosts entries
♾️ Supports unlimited subdomains
3️⃣ Nginx#
🔄 Acts as HTTPS reverse proxy
🎯 Routes based on subdomain
🔌 Proxies to backend services on various ports
4️⃣ Port Forwarding (macOS)#
🔧 Uses pf (packet filter) to forward ports
👤 Allows Nginx to run without root privileges
🚀 Local Development Flow#
| Step | Action |
|---|
| 1 | Developer runs bun setup:local init --map app:3000 --map api:5100 |
| 2 | Script installs and configures mkcert, dnsmasq, and Nginx |
| 3 | Developer starts services: bun run dev:all |
| 4 | Services run on their assigned ports (e.g., Auth on 8001, User on 8002) |
| 5 | Nginx proxies HTTPS requests to appropriate services |
| 6 | Browser trusts certificates without warnings ✅ |
🔧 Microservices Overview#
🎯 Service Responsibilities#
🎯 Service Responsibilities#
| Service | Port | Database | Primary Responsibilities |
|---|
| 🔐 Auth | 8001 | Authentication | Login, registration, JWT tokens, sessions |
| 👤 User | 8002 | Authentication | User profiles, preferences, settings |
| 🏢 Business | 8003 | Platform | Business entity CRUD, verification |
| 📋 Tender | 8004 | Platform | Tender management, bidding logic |
| 💬 Enquiry | 8005 | Platform | Enquiry handling, assignment, responses |
| 📦 Catalog | 8006 | Platform | Product/service catalog, categories |
| 💰 Wallet | 8007 | Wallet | Digital wallet, balance management |
| 💳 Billing | 8008 | Wallet | Payment processing, invoicing |
| 📊 Master | 8009 | Master | Master data, configurations |
| 📈 Activity | 8010 | Platform | Activity tracking, analytics |
| ⚡ Handler | 8011 | — | Event processing, workflow orchestration |
| 🚫 NotFound | 9999 | — | 404 error handling |
⚙️ Technology Stack#
🚀 Runtime & Framework#
Bun: High-performance JavaScript runtime
TypeScript: Type-safe development
🗄️ Database & ORM#
PostgreSQL: Primary database
Prisma: ORM for all domains 🌐 API & Communication#
REST APIs: HTTP/JSON for synchronous communication
Google Cloud Pub/Sub: Asynchronous event-driven messaging via @libs/events wrapper
WebSockets: Real-time updates (where applicable)
Biome: Fast linter and formatter
Prettier: Code formatting
mkcert: Local TLS certificates
☁️ Infrastructure#
Google Cloud Build: CI/CD
Nginx: Production reverse proxy and load balancing
📊 Observability#
Telemetry Library: Custom observability
Logging: Structured logging across services
Metrics: Performance and health metrics
Tracing: Distributed request tracing
📐 Design Principles#
1️⃣ Domain-Driven Design (DDD)#
🎯 Services organized around business domains
🏛️ Clear bounded contexts
💬 Ubiquitous language within each domain
2️⃣ Microservices Best Practices#
🎯 Single Responsibility: Each service has one clear purpose
🚀 Independent Deployment: Services can be deployed independently
🔒 Data Isolation: Each service owns its data
📡 API-First: Well-defined contracts between services
3️⃣ Event-Driven Architecture#
⚡ Asynchronous communication for non-blocking operations
📜 Event sourcing for audit trails
🔄 CQRS pattern where applicable
4️⃣ Security#
🔐 JWT-based authentication
👥 Role-based access control (RBAC)
🔒 Encrypted communication (TLS/SSL)
🛡️ Secure credential storage
🆔 KYC verification integration
5️⃣ Scalability#
↔️ Horizontal scaling of services
📊 Database sharding capability
6️⃣ Resilience#
🔌 Circuit breakers for external calls
🔄 Retry mechanisms with exponential backoff
💚 Health checks and monitoring
7️⃣ Developer Experience#
📦 Monorepo for easier code sharing
📚 Comprehensive documentation
✨ Consistent coding standards
🚀 Future Considerations#
Planned Enhancements#
Planned Enhancements#
📚 Additional Resources#
README.md - Getting started guide and setup instructions
Built with ❤️ by the Bidancer TeamFor questions or contributions, please contact the Bidancer core team.
