Architecture Overview
Vulcan uses a microservices architecture with independent capabilities, each owning its own database. The frontend is a React 19 SPA, with a separate React Native mobile app.
High-Level Architecture
┌─────────────────────────────────────────────────────────────────┐
│ Clients │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ React Web │ │React Native │ │ 3rd Party │ │
│ │ (Vite) │ │ (Expo) │ │ Integrations│ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
└──────────┼─────────────────┼─────────────────┼──────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ API Gateway │
│ (Authentication, Routing, Rate Limiting) │
└─────────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ vulcan-be- │ │ vulcan-be- │ │ vulcan-be- │
│ coresetup │ │ leads │ │ quotation │
│ │ │ │ │ │
│ • Users │ │ • Leads │ │ • Quotes │
│ • Groups │ │ • Customers │ │ • Work Items │
│ • Settings │ │ • Contacts │ │ • Articles │
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
│ │ │
▼ ▼ ▼
[PostgreSQL] [PostgreSQL] [PostgreSQL]Key Principles
One Database Per Capability
Each microservice owns its data. No shared databases.
vulcan-be-coresetup → db-vulcan-be-coresetup (port 5432)
vulcan-be-leads → db-vulcan-be-leads (port 5433)
vulcan-be-quotation → db-vulcan-be-quotation (port 5434)
...Vertical Slice Architecture
Each feature is a self-contained slice with all CRUD operations colocated.
Features/
└── Quotes/
├── GetAllQuotes/
│ ├── GetAllQuotesQuery.cs
│ ├── GetAllQuotesHandler.cs
│ └── GetAllQuotesResponse.cs
├── GetQuote/
├── CreateQuote/
├── UpdateQuote/
└── DeleteQuote/CQRS Pattern
Commands (writes) and Queries (reads) are separated.
csharp
// Query - read operation
public record GetQuoteQuery(Guid Id) : IRequest<QuoteResponse?>;
// Command - write operation
public record CreateQuoteCommand(string Name, Guid CustomerId) : IRequest<CreateQuoteResponse>;Repository Structure
vulcan-workspace/
├── repos/
│ ├── vulcan-web/ # React frontend
│ ├── vulcan-mobile/ # React Native app
│ ├── vulcan-be-coresetup/ # Users, Groups, Settings
│ ├── vulcan-be-leads/ # CRM, Leads, Customers
│ ├── vulcan-be-quotation/ # Quotes, Work packages
│ ├── vulcan-be-contracts/ # Contracts, E-signing
│ ├── vulcan-be-projects/ # Projects, Timelines
│ ├── vulcan-be-invoicing/ # Invoices, Payments
│ ├── vulcan-be-documents/ # Document storage
│ ├── vulcan-be-ai/ # AI services, Embeddings
│ ├── vulcan-be-planning/ # Planning, Scheduling
│ └── vulcan-infrastructure/ # Terraform, Kubernetes
├── docker-compose.yml
└── MakefileData Flow
1. User interacts with React/React Native UI
2. TanStack Query manages API requests
3. Request hits API Gateway
4. Gateway routes to appropriate microservice
5. Mediator dispatches to handler
6. Handler executes business logic
7. EF Core handles database operations
8. Response flows back through layers
9. TanStack Query caches the result
10. UI updates reactivelyCommunication Patterns
Synchronous (HTTP/REST)
For real-time requests between services or from clients.
Client → API Gateway → Microservice → DatabaseAsynchronous (Message Bus)
For background processing and event-driven communication.
Service A → Azure Service Bus → Service B