Skip to content

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
  • Usage: API, Project Management
  • Contents:
  • Business logic
  • Service interfaces
  • DTOs
  • Validators

WebHostConfig.Common

  • Purpose: Web host configuration
  • Usage: API, Project Management
  • 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