Architecture

The Big Picture

Portfolio looks like one application but it's actually two services sharing a database, fronted by a React UI, with several companion services wired in. Here's everything laid out:

Let's walk through each piece.

Service 1: The Portfolio API (Laravel)

This is the main application — a Laravel 11 app running PHP 8.3. It's responsible for:

• Data persistence — all CRUD operations for investors, assets, transactions, valuations
• Business logic — subscription creation, capital call allocation, distribution splitting, fee pro-rating
• Import pipeline — XLSX parsing, validation, row-by-row processing
• Authorization — multi-tenant isolation, role-based permissions, gate checks
• Report generation — PDF rendering for quarterly reports, capital call notices, distribution notices
• Cache orchestration — wrapping every calculation call with tenant-tagged Redis cache

The Action Pattern

Business logic in Portfolio follows a strict pattern: Controller → DTO → Action. Controllers don't contain business logic — they validate the request, build a Data Transfer Object, and hand it to an Action class.

For example, creating a capital call:

1. CapitalCallController validates the request via a Form Request
2. Builds a CreateCapitalCallDto with the validated data
3. Calls CreateCapitalCallAction::execute($dto)
4. The Action creates the Transaction, CashFlows, updates unit holdings, and fires events
5. Event listeners clear caches and trigger NAV recalculations

There are Action classes for every operation: CreateDrawdownAction, CreateRedemptionTransactionAction, CreateFeeAction, ReverseImportAction, and dozens more.

Service 2: The Calculation Service (Go)

This is a dedicated Go microservice that performs all financial calculations. It communicates exclusively via gRPC on port 50051.

What It Computes (27 endpoints)

The calc service exposes 27 gRPC methods. They fall into these categories:

How It Works Under the Hood

Every request to the calc service includes:

• SchemaName — which tenant's data to query (e.g., tenant_42)
• DB credentials — username/password for that request
• Scope — which investor(s) and/or asset(s) to calculate for
• Optional: DestinationCurrency — convert all amounts to this currency
• Optional: PreDatetime — point-in-time cutoff ("show me the numbers as of Q4 2025")

The service then:

1. Opens a connection to the tenant's PostgreSQL schema
2. Fires parallel goroutines for each core calculation (committed, called, paid-in, distributions, etc.)
3. Aggregates raw results into derived metrics (DPI = distributions / paid-in, etc.)
4. Converts currencies using the rates database if needed
5. Returns the computed protobuf response

The Three API Surfaces

Portfolio exposes three distinct APIs, each serving a different consumer. This is a critical architectural detail — data enters the system through different doors.

Multi-Tenant Data Isolation

Portfolio uses Spatie Multi-Tenancy with a schema-per-tenant pattern in PostgreSQL:

Tenant resolution happens via middleware. For the REST API, the tenant is determined from the request domain/subdomain. For the Machine API, it's from the DELIOTENANT header. The Go calc service receives the schema name explicitly with every gRPC request.

The Cache Layer

All calculation results from the Go service are cached in Redis by the Laravel app. This is critical for performance — without caching, every page load would trigger expensive gRPC computation.

Aspect	How It Works
Cache key structure	Tagged by tenant + asset ID(s) + investor ID(s) for surgical invalidation
When caches are cleared	On any data mutation — transaction creation, valuation update, deletion. Events fire ClearAllCaches or targeted cache tags.
Cache warming	cache:clear-and-warm --tenant={id} artisan command pre-computes common dashboard calculations
Go-side caching	The Go service also caches exchange rates in-memory (bigcache) with 24h TTL

Companion Services

Request Lifecycle: End to End

Let's trace what happens when an internal user views the Portfolio dashboard:

Knowledge Check

What's Next

You now understand the system's moving parts and how they connect. Next, we'll zoom in on the data model — the entities stored in those tenant schemas, how they relate to each other, and the dependency chain you need to follow when setting up a new client.