System Architecture

High-Level Architecture

PhotoFlow follows a microservices architecture with each service owning its domain and database. Services communicate through internal events and REST APIs.

Microservices Overview

Core Services

Service	Responsibility	Database
Photoflow	Album workflow, photos, feedback, state machine	`pfl-dev`
Storage	Cloud provider integration, file sync	`pfl-dev`
Identity	User authentication, token management	`pfl-dev`
Organization	Multi-tenant organization management	`pfl-dev`

Supporting Services

Service	Responsibility
Provider	External provider configurations
Sender	Email/SMS notification delivery
AppGateway	API routing, authentication middleware

Service Architecture Pattern

Each service follows Clean Architecture with four layers:

Service/
├── Service.API/          # Controllers, DTOs, Middleware
├── Service.Application/  # Use Cases, Commands, Queries, Handlers
├── Service.Domain/       # Entities, Value Objects, Domain Events
└── Service.Infrastructure/ # Repositories, External Services, EF Context

Layer Responsibilities

Communication Patterns

Synchronous Communication (REST APIs)

Services expose REST APIs for synchronous operations:

Frontend → AppGateway → Service API → Application Layer → Domain/Infrastructure

Asynchronous Communication (Internal Events)

Services publish and subscribe to internal events using IInServiceEventBus:

// Publishing an event
await eventBus.Publish(new AlbumStateMachineTriggeredEvent
{
    AlbumId = album.Id,
    FromState = previousState,
    ToState = newState
}, cancellationToken);

// Subscribing to events (via MediatR)
public class AlbumStateMachineTriggeredEventHandler 
    : INotificationHandler<AlbumStateMachineTriggeredEvent>
{
    public async Task Handle(AlbumStateMachineTriggeredEvent notification, ...)
    {
        // Handle the event
    }
}

Real-time Communication (SignalR)

SignalR is used for pushing real-time updates to connected clients:

Data Flow

Album Sync Flow

BuildingBlocks (Shared Libraries)

The BuildingBlocks directory contains shared libraries used across all services:

Library	Purpose
`BuildingBlocks.Authentication`	JWT authentication, authorization policies
`BuildingBlocks.Caching`	Redis caching abstractions
`BuildingBlocks.Cloud`	Cloud provider integrations (Google, AWS)
`BuildingBlocks.Core`	Base classes, common utilities
`BuildingBlocks.Domain`	Shared domain primitives
`BuildingBlocks.Exception`	Custom exception types
`BuildingBlocks.Interceptor`	Cross-cutting concerns
`BuildingBlocks.Library`	Helper utilities
`BuildingBlocks.Messaging`	Event bus abstractions
`BuildingBlocks.Persistence`	EF Core configurations
`BuildingBlocks.SignalR`	SignalR hub and notification service
`BuildingBlocks.StateMachine`	State machine abstractions

Security Architecture

Authentication Flow

Authorization Policies

Policy	Roles Allowed	Use Case
`Photographer`	photographer, org_admin	Album management operations
`Admin`	org_admin	Organization-level operations
`SuperAdmin`	supper_admin	System-wide operations
`Anonymous`	anonymous	Public client operations
`PhotographerOrAnonymous`	photographer, org_admin, anonymous	Shared operations (transitions)

Infrastructure Architecture

Kubernetes Deployment

Helm Chart Structure

shin-helm-chart/
├── Chart.yaml
├── values.yaml
├── templates/
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── configmap.yaml
│   ├── component-deployments.yaml
│   └── component-services.yaml

Modules Overview
API Documentation
Deployment Guide

Last modified: 25 February 2026