Skip to content

1. Microservices Architecture

Date: 2025-11-04
Status: Accepted
Deciders: Core Team
Related: N/A (foundational decision)

Context

SPOT (Spear-Phishing Overwatching Tool) is an email security platform that analyzes emails for spear-phishing attempts using various detection techniques (NLP, LLM, rule-based). The platform needs to:

  • Support multiple analyzer types with different technologies and requirements
  • Scale individual components independently based on load
  • Allow different teams to work on different analyzers without conflicts
  • Enable adding new analyzers without modifying core platform
  • Isolate failures to prevent cascading system failures
  • Support different programming languages for specialized analyzers

Decision

Adopt a microservices architecture with:

  • Central orchestration service coordinating analysis workflows
  • Independent analyzer services (NLP, LLM, context-based)
  • API gateway for external clients
  • Message broker for async communication
  • Shared contracts package for interface definitions

Rationale

  1. Modularity: Each analyzer is an independent service with its own codebase, dependencies, and deployment
  2. Scalability: Can scale high-load analyzers independently (e.g., scale NLP analyzer more than LLM analyzer)
  3. Technology flexibility: Different analyzers can use different ML frameworks, languages, or tools
  4. Team autonomy: Teams can develop, test, and deploy analyzers independently
  5. Fault isolation: If one analyzer fails, others continue working
  6. Extensibility: New analyzers can be added by creating new services implementing the contract

Consequences

Positive

  • Clear service boundaries and responsibilities
  • Independent deployment and scaling of components
  • Technology choice flexibility per service
  • Easier to understand and maintain individual services
  • Parallel development by multiple teams
  • Graceful degradation when analyzers fail

Negative

  • Additional complexity in deployment and operations
  • Need for service discovery and orchestration
  • Network communication overhead between services
  • More complex testing (need integration tests)
  • Distributed system debugging challenges
  • Infrastructure overhead (more containers/processes)

Alternatives Considered

Alternative 1: Monolithic Application

  • Pros:
  • Simpler deployment (single application)
  • No network overhead
  • Easier local development
  • Simpler testing
  • Cons:
  • All analyzers must use same technology stack
  • Cannot scale components independently
  • Tight coupling between analyzers
  • Large codebase difficult to navigate
  • Single point of failure
  • Requires full redeployment for any change
  • Why rejected: Doesn't support technology flexibility and independent scaling we need

Alternative 2: Plugin Architecture

  • Pros:
  • Single process, no network overhead
  • Dynamic loading of analyzers
  • Shared resources and memory
  • Cons:
  • All plugins must be in same language
  • Plugin failures can crash main process
  • Difficult to isolate resource usage
  • Cannot deploy plugins independently
  • Shared dependency conflicts
  • Why rejected: Too restrictive for supporting diverse analyzer types

Implementation Notes

  • Use Docker containers for each service
  • Implement health checks for all services
  • Use RabbitMQ for async messaging between services
  • Define clear service contracts using spot-sdk package
  • Services communicate via REST APIs and message queues
  • Each service has its own database schema namespace

References