Added c4 model

Author: Nasruddin

notes/archtecture.md

@@ -0,0 +1,95 @@
+# Course Management System
+
+
+This section describes the C4 model for the Course Management System, a Spring Boot microservices application with Course, Review, and CourseComposite services, deployed using Docker Compose and Kubernetes.
+
+### Level 1: System Context Diagram
+**Description**: High-level view of the system and its external actors.
+
+- **System**: Course Management System
+ - A microservices-based application for managing courses and reviews.
+- **Actors**:
+ - **User**: Browses courses and submits reviews (via browser/API).
+ - **Administrator**: Manages content and monitors system health.
+- **External Systems**:
+ - **Keycloak**: Authentication and authorization (OIDC/OAuth2).
+ - **Grafana Observability Stack**: Grafana, Loki, Tempo, Fluent-bit, and OpenTelemetry (Otel) for monitoring and logging.
+- **Interactions**:
+ - User → System: HTTP requests via Gateway.
+ - System → Keycloak: Authenticates users.
+ - System → Grafana Stack: Sends observability data.
+
+### Level 2: Container Diagram
+**Description**: Breaks the system into deployable units.
+
+- **Containers**:
+ 1. **API Gateway (Spring Cloud Gateway)**
+ - Tech: Spring Boot + Spring Cloud Gateway
+ - Role: Routes requests, enforces security.
+ - Interactions: User → Gateway → CourseComposite.
+ 2. **CourseComposite (Aggregate Microservice)**
+ - Tech: Spring Boot
+ - Role: Aggregates Course and Review data.
+ - Interactions: Gateway → CourseComposite → Course/Review.
+ 3. **Course (Core Microservice)**
+ - Tech: Spring Boot
+ - Role: Manages course data.
+ - Database: PostgreSQL
+ - Interactions: CourseComposite → Course → PostgreSQL.
+ 4. **Review (Core Microservice)**
+ - Tech: Spring Boot
+ - Role: Manages review data.
+ - Database: MongoDB
+ - Interactions: CourseComposite → Review → MongoDB.
+ 5. **Keycloak**
+ - Role: External auth provider.
+ - Interactions: Gateway → Keycloak.
+ 6. **Observability Stack**:
+ - **Fluent-bit**: Log collection.
+ - **OpenTelemetry (OTel)**: Trace.
+ - **Loki**: Log storage.
+ - **Tempo**: Trace storage.
+ - **Grafana**: Visualization.
+ - Interactions: Microservices → Fluent-bit/OTel → Loki/Tempo → Grafana.
+
+### Level 3: Component Diagram
+**Description**: Key components within containers.
+
+- **API Gateway**:
+ - Routing Component (Spring Cloud Gateway).
+ - Security Component (Keycloak integration).
+ - Observability Agent (OTel + Fluent-bit).
+- **CourseComposite**:
+ - Course Client (REST).
+ - Review Client (REST).
+ - Aggregation Logic.
+ - Observability Agent.
+- **Course**:
+ - Course Controller (REST).
+ - Course Service (Logic).
+ - Course Repository (JPA/PostgreSQL).
+ - Observability Agent.
+- **Review**:
+ - Review Controller (REST).
+ - Review Service (Logic).
+ - Review Repository (MongoDB).
+ - Observability Agent.
+
+### Level 4: Deployment Notes
+**Description**: Two deployment setups.
+
+1. **Docker Compose Setup**:
+ - Containers: Gateway, CourseComposite, Course + PostgreSQL, Review + MongoDB, Keycloak, Observability Stack.
+ - Networking: Single Docker network.
+ - Config: `docker-compose.yml`.
+
+2. **Kubernetes Setup with Tilt**:
+ - Pods: Gateway, CourseComposite, Course + PostgreSQL, Review + MongoDB, Keycloak, Observability Pods.
+ - Resources: Ingress, Services, ConfigMaps/Secrets, PVCs.
+ - Tilt: Automates dev with live updates.
+ - Observability: Fluent-bit DaemonSet
+
+### Additional Notes
+- **Tech**: Spring Boot, Spring Cloud, JPA, MongoDB driver, OTel, Fluent-bit.
+- **Interactions**: REST/HTTP, JDBC, MongoDB protocol.
+- **Scalability**: Kubernetes supports replicas; Docker Compose for local dev.