project-documentation/week1.md

Project Context: PetCLinic Microservices -> AWS

Context and Scope

This project will migrate the Spring PetClinic Microservices demo from its local/on-premise setup to AWS Cloud. The focus is infrastructure modernization, CI/CD automation, observability, and resilience but not application feature development.

Stakeholders

Role	Responsibility
Project Sponsor	Funding, final approval
Project Manager	Scheduling, stakeholder coordination
Cloud Architect	Architecture, service selection
Dev Lead	App changes for cloud readiness
DevOps Engineer	CI/CD, IaC, deployments, monitoring
Security Team	IAM, encryption
End Users / Demo Audience	Acceptance and usability feedback

Expectations

• No app feature development unless necessary for cloud deployment.
• AWS is the only target cloud

Objectives

• Run full PetClinic microservices on AWS with CI/CD.
• Observability: logs, metrics, traces for 100% of services.
• Cost target: keep monthly infra cost under a defined limit (set by Project Sponsor).
• Security: secrets encrypted, least-privilege IAM, HTTPS for all endpoints.

Deadlines

Milestone	Date
Project approval	Oct 27, 2025
CI/CD & Automation	Nov 3, 2025
Infrastructure	Nov 10, 2025
Data	Nov 17, 2025
Observability	Nov 24, 2025
Prep: Presentation, Demo, and Pre-defense	Dec 3, 2025

In Scope

Included items	Objective
Application	Only necessary changes (if applicable) to facilitate cloud integration
Infrastructure	Design and deploy a reproducible, cloud-native architecture
CI/CD Automation	Implement automated build, test, and deployment pipelines
Containerization	Adapt existing microservices to use AWS.
Monitoring & Logging	Centralized logs, metrics, and traces
Security & IAM	Least-privilege IAM roles, encryption, and subnet segmentation.
Backup & Recovery	Redundancy, failover, backup, BCP/DRP
Documentation	Architecture diagrams, specifications, and operational runbooks.

Out of Scope

Excluded items	Reason
Application feature or UI changes	Funcitoniality remains unchanged.
Multi-cloud or hybrid deployment	Focus solely on AWS environment.
Cost-optimization	Addressed in a later project if necessary

Requirements

Functional requirements

Stakeholder / Role	Requirement	Description
Developers	Continuous Integration	Each merge must trigger automated build, test, and image creation.
	Local to Cloud Parity	Development environment must mirror AWS setup.
DevOps Engineers	Automated Deployment	CI/CD pipeline must deploy microservices to Dev, Staging, and Prod environments automatically.
	Test Automation	Integration tests must run automatically in CI/CD pipeline.
	Infrastructure as Code	All AWS resources defined through configuration files
	Monitoring & Alerts	Centralized logging, metrics, and tracing for all microservices. Automated alerting for service downtime or threshold breaches.
	Scalability	Services must be scalable
Security Team	Access Control	Roles per service with least-privilege permissions.
	Secrets Management	All secrets stored securely.
Product / Management	Availability & Demo Readiness	System must be reliable and presentable for client or internal demos.
End Users (Demo Audience)	Stable Access	Web UI and APIs must remain responsive under typical load.

Non-Functional Requirements

Category	Requirement	Standard
Development	Local to Cloud parity	Docker Compose or local ECS simulation
Maintainability	IaC	Code stored in version control
Performance	Pipeline execution time	< 10 minutes per merge
	Scaling	Services can be scaled horizontally
	API / UI response	p95 latency < 200 ms under normal demo load
Reliability	Deployment success rate	≥ 99% successful deployments
	Alert response	Alerts trigger within < 5 minutes of failure detection
	Error tolerance	< 0.1% failed requests
Availability	System uptime	≥ 99.9% uptime
Observability	Logs, Metrics, Traces	Centralized in monitoring solution
Security	Least-privileged Roles	Roles restricted per service; no default full-access policies
	Secret encryption	Secrets stored in AWS
Continuity	RPO / RTO	RPO ≤ 5 min, RTO ≤ 30 min using RDS Multi-AZ and S3 backups
Cost	Budget target	Monthly AWS cost ≤ defined cap

System Components — Spring PetClinic Microservices

Component	Role / Function	Dependencies	Notes
spring-petclinic-admin-server	Provides admin UI and dashboards	Microservices, Config Server	Central monitoring and management interface
spring-petclinic-api-gateway	Routes external requests to microservices	Customers, Vets, Visits, GenAI services	Single entry point for all APIs; can handle load balancing
spring-petclinic-config-server	Centralized configuration	Git repo	Supplies configuration to all microservices at runtime
spring-petclinic-customers-service	Manages customer data	RDBMS, Config Server	Core domain service
spring-petclinic-vets-service	Manages veterinary staff	RDBMS, Config Server	Lookup and assignment of vets
spring-petclinic-visits-service	Manages pet visit records	RDBMS, Customers Service	Tracks appointments and visit history
spring-petclinic-genai-service	Optional AI / generative service	Microservices, RDBMS	Provides a chatbot interface to the application.
spring-petclinic-discovery-server	Service registry / discovery	All microservices	Enables service-to-service discovery
RDBMS	Persistent storage	Customers, Vets, Visits	Single relational database supporting multiple services

Architecture and Specifications

Project

• Kanban as agile methodology
• Breakdown of work and phases:
  • Infrastructure Setup
  • Service Orchestration
  • Configuration Management
  • CI/CD Automation
  • Security
  • Resilience
  • Observability
• Assignments:

Role	Responsibilities
Cloud Architect	Design AWS target architecture, network, and IAM structure
DevOps Engineer	Build CI/CD pipelines, container orchestration, monitoring setup
Dev Lead	Containerize services, modify configs for cloud compatibility
Database Engineer	Migrate data from local RDBMS to AWS RDS, manage schema updates
Security Team	Set up access and roles for services
Everyone	Validate deployments, pipeline runs, rollback testing
Project Lead	Manage Asana Kanban board, ensure alignment and progress tracking

Source Code

• Architecture Type: Microservices deployed via containers, managed by ECS/EKS, behind an AWS Application Load Balancer (ALB).
• Review via pull request process:
  • All commits merged via PRs.
  • Peer review required before merging.
• Vaildation: Run tests during pipeline build