Architecture Overview

Vulcan uses a microservices architecture with 11 independent capabilities, each owning its own database. The system includes a YARP API Gateway for routing, a Better Auth service for authentication, React 19 web frontend, and React Native mobile app.

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                          Clients                                 │
│   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐          │
│   │  React Web  │   │React Native │   │   3rd Party │          │
│   │   (Vite)    │   │   (Expo)    │   │  Integrations│          │
│   └──────┬──────┘   └──────┬──────┘   └──────┬──────┘          │
└──────────┼─────────────────┼─────────────────┼──────────────────┘
           │                 │                 │
           │                 │                 │ HTTPS
           ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                  API Gateway (YARP - Port 8080)                  │
│      Rate Limiting | Health Checks | OpenAPI Aggregation        │
└──────────────────────────────┬──────────────────────────────────┘
                               │
        ┌──────────────────────┼──────────────────────┐
        │                      │                      │
        ▼                      ▼                      ▼
┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│ Auth Service │      │   Leads      │      │  Quotation   │
│ (Port 3000)  │      │ (Port 5000)  │      │ (Port 5000)  │
│ Better Auth  │      │  .NET 10     │      │  .NET 10     │
│ Multi-tenant │      │ • Leads      │      │ • Quotes     │
│ • Sign up/in │      │ • Customers  │      │ • Work Items │
│ • 2FA        │      │ • Contacts   │      │ • Articles   │
│ • Orgs       │      │              │      │              │
└──────┬───────┘      └──────┬───────┘      └──────┬───────┘
       │                     │                     │
       ▼                     ▼                     ▼
    [auth DB]           [leads DB]            [quotation DB]

... and 8 more microservices (contracts, projects, invoicing,
    documents, ai, planning, coresetup) each with their own database

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>;

Complete Service Inventory

Backend Services (.NET 10 Microservices)

vulcan-be-coresetup - Core setup, users, groups, settings
vulcan-be-leads - CRM, leads, customers, contacts
vulcan-be-quotation - Quotes, work packages, articles
vulcan-be-contracts - Contracts, e-signing integration
vulcan-be-projects - Projects, timelines, milestones
vulcan-be-invoicing - Invoices, payments, accounting
vulcan-be-documents - Document storage and management
vulcan-be-ai - AI services, MCP gateway, embeddings
vulcan-be-planning - Planning, scheduling, resources

Gateway & Auth

vulcan-be-gateway - YARP API Gateway (Port 8080)
vulcan-be-auth - Better Auth service (Port 3000)

Frontend

vulcan-web - React 19 web application
vulcan-mobile - React Native mobile app

Infrastructure

vulcan-infrastructure - Terraform, Kubernetes, Helm
vulcan-docs - Documentation site (VitePress)
vulcan-product-guide - Product team spec tool

Repository Structure

vulcan-workspace/
├── repos/
│   ├── vulcan-web/              # React 19 frontend
│   ├── vulcan-mobile/           # React Native + Expo
│   ├── vulcan-be-gateway/       # YARP API Gateway (Port 8080)
│   ├── vulcan-be-auth/          # Better Auth (Port 3000)
│   ├── 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
│   ├── vulcan-docs/             # Documentation (this site)
│   └── vulcan-product-guide/    # Product team tool
├── docker-compose.yml
├── Makefile
└── .agentic/ (workspace orchestration, expertise)

Data Flow

1. User interacts with React/React Native UI
2. TanStack Query manages API requests
3. Request hits API Gateway (YARP on port 8080)
4. Gateway validates rate limits and forwards request
5. Auth service validates JWT token (if auth route)
6. Gateway routes to appropriate microservice
7. Microservice validates JWT and extracts organization context
8. Mediator dispatches to handler (CQRS pattern)
9. Handler executes business logic
10. EF Core handles database operations
11. Response flows back through layers
12. TanStack Query caches the result
13. UI updates reactively

Authentication Flow

1. User enters credentials in UI
2. POST /api/auth/sign-in → Auth Service
3. Auth Service validates credentials
4. Auth Service creates session + JWT token with organization context
5. Token returned to client (HttpOnly cookie for web, secure storage for mobile)
6. Client includes Authorization: Bearer <token> in all subsequent requests
7. Gateway forwards token to microservices
8. Microservices validate token and extract organizationId
9. Global query filter applied: WHERE organization_id = <organizationId>
10. User sees only their organization's data

Communication Patterns

Synchronous (HTTP/REST)

For real-time requests between services or from clients.

Client → API Gateway → Microservice → Database

Asynchronous (Message Bus)

For background processing and event-driven communication.

Service A → Azure Service Bus → Service B

Technology Choices

Layer	Technology	Why?
Frontend	React 19 + Vite	Latest React with modern build tooling
Mobile	React Native + Expo	Cross-platform with minimal native code
Gateway	YARP (.NET)	High-performance reverse proxy from Microsoft
Auth	Better Auth	Modern, TypeScript-native auth solution
Backend	.NET 10	LTS release with excellent performance
Pattern	Vertical Slice + CQRS	Feature-focused, maintainable code
Database	PostgreSQL 16	Mature, reliable, excellent JSON support
Orchestration	Kubernetes (AKS)	Industry standard, Azure-managed
IaC	Terraform	Declarative infrastructure as code
CI/CD	GitLab CI	Integrated with our Git workflow

Next Steps

Authentication Service - Better Auth with multi-tenancy
API Gateway - YARP reverse proxy details
Frontend Architecture - React 19 web app
Backend Architecture - Microservices patterns
Mobile Architecture - React Native app
Infrastructure - Azure deployment

Architecture Overview ​

High-Level Architecture ​

Key Principles ​

One Database Per Capability ​

Vertical Slice Architecture ​

CQRS Pattern ​

Complete Service Inventory ​

Backend Services (.NET 10 Microservices) ​

Gateway & Auth ​

Frontend ​

Infrastructure ​

Repository Structure ​

Data Flow ​

Authentication Flow ​

Communication Patterns ​

Synchronous (HTTP/REST) ​

Asynchronous (Message Bus) ​

Technology Choices ​

Next Steps ​