.. include:: .special.rst
9. Architecture Decisions
============================

This chapter documents key architectural decisions made during the design and implementation of the
system.

.. raw:: html
   :file: _images/architecture_decisions.html

Each decision follows a structured format to capture important details:

| **Title** – A short, descriptive name for the decision.
| **Context** – The problem, background, and reasoning for the decision.
| **Decision** – The chosen solution and justification.
| **Consequences** – The impact of the decision, including trade-offs and alternatives considered.


=================================
9.1 FastAPI for Backend Services
=================================

| **Title:** FastAPI for Backend Services
| **Context**: The backend requires a high-performance, async-first API framework for
  handling machine learning workloads.
| **Decision:** We selected FastAPI due to its automatic OpenAPI documentation, async support,
   and performance optimizations.
| **Consequences:**
+ :green:`Faster response times with async I/O`
+ :green:`Built-in validation via Pydantic`
- :maroon:`Requires developer familiarity with async paradigms`


=================================
9.2 Deployment Strategy: Docker
=================================

| **Title:** Deployment Strategy: Docker
| **Context**: The system needs a scalable, containerized deployment approach
  that supports multi-environment staging and production.
| **Decision:** We use Docker for containerization for orchestration, ensuring portability and scalability.
| **Consequences:**
+ :green:`Simplified dependency management with Docker`
+ :green:`Easier Deployment (independent services)`
- :maroon:`More complexity`

=================================
9.3 Database Choice: PostgreSQL
=================================


| **Title:** Database Choice: PostgreSQL
| **Context**: The system requires a reliable, ACID-compliant database to store structured data.
| **Decision:** We chose PostgreSQL due to its robust transactions, scalability, and strong SQL support.
| **Consequences:**
+ :green:`Supports advanced queries and analytics`
+ :green:`Open-source with strong community support`
- :maroon:`Requires tuning for large-scale ML workloads`

==================================================
9.4 Storage: MinIO as S3-Compatible Object Store
==================================================

| **Title:** Storage: MinIO as S3-Compatible Object Store
| **Context**: Machine learning workflows need a scalable, durable storage solution for datasets.
| **Decision:** We use MinIO, an S3-compatible storage service, for fast, distributed object storage.
| **Consequences:**
+ :green:`Works seamlessly with MLflow for model tracking`
+ :green:`Scalable and deployable on-premise`
- :maroon:`Requires additional backup strategies for data persistence`

=====================================================
9.5 Monitoring & Logging: Prometheus + Grafana + Loki
=====================================================

| **Title:** Monitoring & Logging: Prometheus + Grafana + Loki
| **Context**: The system requires comprehensive observability to detect failures and monitor performance.
| **Decision:**

- Prometheus for metrics collection
- Grafana for visualization
- Loki for centralized logging

| **Consequences:**
+ :green:`Unified monitoring stack improves debugging`
+ :green:`Customizable dashboards for system health`
- :maroon:`Additional infrastructure overhead`

=====================================================
9.5 CI/CD Strategy: GitHub Actions for Automation
=====================================================

| **Title:** CI/CD Strategy: GitHub Actions for Automation
| **Context**: Automated testing, building, and deployment are required for continuous integration and delivery.
| **Decision:** We use GitHub Actions for automating tests, builds, and deployments.
| **Consequences:**
+ :green:`Faster release cycles with automated testing`
+ :green:`Seamless Git-based workflow integration`
- :maroon:`Requires maintaining workflow configurations`

=====================================================
9.6 API Gateway & Reverse Proxy: Nginx
=====================================================

| **Title:** API Gateway & Reverse Proxy: Nginx
| **Context**: We need a secure entry point for incoming requests and SSL termination for public services.
| **Decision:** Nginx is used as a reverse proxy and load balancer.
| **Consequences:**
+ :green:`Improved security with rate limiting and DDoS protection`
+ :green:`Load balancing across backend services`
- :maroon:`Requires ongoing configuration updates`