Skip to content

DEPRECATED: This document provides a generic system overview. For the comprehensive domain architecture including data flow, three-level data model, study lifecycle, and PRISMA integration, see Platform Architecture.

This file is retained for reference but is no longer the primary architecture document.

System Architecture Overview

Executive Summary

SyRF (Systematic Review Facility) is a microservices-based platform for conducting systematic reviews and meta-analyses. The system follows Domain-Driven Design (DDD) principles, uses event-driven architecture, and deploys via GitOps to Kubernetes.

Architecture Principles

Design Philosophy

  • Microservices: Independent services with clear boundaries
  • Domain-Driven Design: Business logic organized around domains
  • Event-Driven: Asynchronous communication via message bus
  • API-First: RESTful APIs with OpenAPI documentation
  • Cloud-Native: Containerized, orchestrated, and scalable

Technical Principles

  • Single Responsibility: Each service has one clear purpose
  • Loose Coupling: Services communicate via contracts
  • High Cohesion: Related functionality grouped together
  • Eventual Consistency: Distributed data with eventual sync
  • Observability: Comprehensive logging, metrics, and tracing

System Components

Core Services

API Service (syrf-api)

  • Purpose: Main REST API gateway for client applications
  • Technology: .NET 10.0, ASP.NET Core
  • Database: MongoDB (shared)
  • Port: 8080
  • Key Features:
  • Authentication/Authorization
  • Request routing
  • Response aggregation
  • API versioning

Project Management Service (syrf-project-management)

  • Purpose: Manages projects, studies, and systematic reviews
  • Technology: .NET 10.0, DDD architecture
  • Database: MongoDB (domain-specific collections)
  • Port: 8081
  • Key Features:
  • Project lifecycle management
  • Study organization
  • Review workflows
  • Collaboration features

Background Jobs Service (syrf-quartz)

  • Purpose: Scheduled and background task execution
  • Technology: .NET 10.0, Quartz.NET
  • Database: MongoDB (job storage)
  • Port: 8082
  • Key Features:
  • Scheduled reports
  • Data processing
  • Cleanup tasks
  • Notification dispatch

Web Frontend (syrf-web)

  • Purpose: User interface for the platform
  • Technology: Angular, TypeScript
  • Port: 80
  • Key Features:
  • Responsive SPA
  • Real-time updates
  • Rich text editing
  • Data visualization

S3 Event Processor (syrf-s3-notifier)

  • Purpose: Processes S3 file upload events
  • Technology: .NET 10.0, AWS Lambda
  • Deployment: AWS Lambda (serverless)
  • Key Features:
  • File upload notifications
  • Metadata extraction
  • Event publishing

Shared Libraries

SharedKernel

  • Purpose: Core domain models and interfaces
  • Usage: All .NET services
  • Contents:
  • Domain entities
  • Value objects
  • Domain events
  • Common interfaces

Mongo.Common

  • Purpose: MongoDB data access layer
  • Usage: API, Project Management
  • Contents:
  • Repository patterns
  • Connection management
  • Query builders
  • Migration support

AppServices

  • Purpose: Application service layer (hosts S3 file services since PR #2591)
  • Usage: API, Project Management
  • Contents:
  • Business logic
  • Service interfaces
  • DTOs
  • Validators
  • S3 file services (S3Settings, IS3PostSigner, S3PostSigner, S3SignerBase — moved from SharedKernel in PR #2591)

WebHostConfig.Common

  • Purpose: Web host configuration (generic bootstrap only; feature-specific DI wiring lives in each feature lib's own ServiceRegistry subclass — see ADR-008)
  • Usage: API, Project Management, Quartz
  • Contents:
  • Middleware
  • Logging setup
  • OpenAPI config
  • Health checks

Data Architecture

Primary Database

  • Type: MongoDB
  • Version: 6.x
  • Deployment: Replica set for HA
  • Collections:
  • Projects
  • Studies
  • Users
  • Reviews
  • Documents

Message Bus

  • Type: RabbitMQ via MassTransit
  • Pattern: Publish/Subscribe
  • Messages:
  • Domain events
  • Integration events
  • Commands
  • Notifications

File Storage

  • Type: AWS S3 or compatible
  • Structure:
  • /uploads/ - User uploads
  • /exports/ - Generated exports
  • /reports/ - System reports

Deployment Architecture

Container Platform

  • Orchestration: Kubernetes
  • Ingress: NGINX Ingress Controller
  • Service Mesh: Optional (Istio/Linkerd)
  • Registry: GitHub Container Registry

GitOps Flow

graph LR
    A[Code Push] --> B[GitHub Actions]
    B --> C[Build & Test]
    C --> D[Docker Build]
    D --> E[Push to GHCR]
    E --> F[Update GitOps Repo]
    F --> G[ArgoCD Sync]
    G --> H[Deploy to K8s]

Environments

  • Development: Local Docker Compose
  • Preview: Ephemeral PR environments
  • Staging: Pre-production testing
  • Production: Live system

Security Architecture

Authentication & Authorization

  • Method: JWT tokens
  • Provider: Configurable (Auth0, Azure AD)
  • Scopes: Role-based access control
  • Session: Stateless

Network Security

  • TLS: All external traffic encrypted
  • Network Policies: Kubernetes NetworkPolicies
  • Secrets: External Secrets Operator (ESO)
  • Scanning: Container vulnerability scanning

Data Security

  • Encryption at Rest: Database encryption
  • Encryption in Transit: TLS 1.2+
  • PII Handling: GDPR compliant
  • Audit Logs: Comprehensive activity logging

Observability

Logging

  • Aggregation: Loki or CloudWatch
  • Format: Structured JSON
  • Levels: Debug, Info, Warning, Error
  • Correlation: Request ID tracing

Metrics

  • Collection: Prometheus
  • Visualization: Grafana
  • Key Metrics:
  • Request rates
  • Error rates
  • Response times
  • Resource usage

Tracing

  • System: OpenTelemetry
  • Backend: Jaeger or X-Ray
  • Coverage: All service boundaries

Scalability & Performance

Horizontal Scaling

  • Services: Auto-scaling via HPA
  • Database: Read replicas
  • Cache: Redis (future)

Performance Targets

  • API Response: < 200ms (p95)
  • Page Load: < 2s
  • Availability: 99.9%
  • RTO: < 1 hour
  • RPO: < 1 hour

Development Workflow

Version Control

  • Strategy: Trunk-based development
  • Branching: Feature branches for PRs
  • Commits: Conventional commits

CI/CD Pipeline

  • Build: GitHub Actions
  • Versioning: GitVersion (semantic)
  • Testing: Unit, Integration, E2E
  • Deployment: GitOps via ArgoCD

Local Development

  • IDE: Visual Studio / VS Code
  • Containers: Docker Compose
  • Hot Reload: Supported
  • Debugging: Remote debugging

Future Enhancements

Planned Features

  • GraphQL API gateway
  • Real-time collaboration (WebSockets)
  • Machine learning integration
  • Advanced analytics dashboard

Technical Improvements

  • Service mesh implementation
  • Distributed caching (Redis)
  • Event sourcing for audit
  • Multi-region deployment

References