MediCore - Medical Profile Management System

A comprehensive microservices architecture for Medi Core

Architecture Overview

API Gateway

Core Services

Databases

Messaging

Infrastructure

flowchart TD subgraph External[External Clients] CLIENT[Client App] ADMIN[Admin Console] end subgraph Gateway[API Gateway] GW[Gateway Service\n:8084] end subgraph Internal[Internal Services] AUTH[Auth Service\n:8085]:::service PROFILE[Medical Profile Service\n:8081]:::service BILLING[Medical Billing Service\n:8082]:::service ANALYTICS[Medical Analytics Service\n:8083]:::service end subgraph Data[Data Layer] AUTH_DB[(Auth DB\nPostgreSQL)]:::db PROFILE_DB[(Profile DB\nPostgreSQL)]:::db KAFKA[(Kafka\nEvent Bus)]:::messaging end CLIENT -->|HTTP Requests| GW ADMIN -->|HTTP Requests| GW GW -->|/auth/*| AUTH GW -->|/api/medical-profiles/*| PROFILE GW -->|Validate JWT| AUTH PROFILE -->|gRPC| BILLING PROFILE -->|Kafka Events| KAFKA ANALYTICS -->|Consume| KAFKA AUTH --> AUTH_DB PROFILE --> PROFILE_DB classDef gateway fill:#dbeafe,stroke:#3b82f6; classDef service fill:#e0f2fe,stroke:#0ea5e9; classDef db fill:#fef3c7,stroke:#f59e0b; classDef messaging fill:#f3e8ff,stroke:#8b5cf6; classDef infra fill:#f3f4f6,stroke:#9ca3af; class GW gateway; class AUTH,PROFILE,BILLING,ANALYTICS service; class AUTH_DB,PROFILE_DB db; class KAFKA messaging;

Key Architectural Decisions

API Gateway Pattern: Single entry point for all client requests with centralized authentication
Microservices Architecture: Independently deployable services with bounded contexts
Polyglot Persistence: Dedicated databases per service with appropriate data models
Event-Driven Communication: Kafka for asynchronous event processing between services
gRPC for Service-to-Service: High-performance RPC for synchronous communication
Containerized Deployment: Docker containers with AWS ECS Fargate for serverless compute

Microservices Breakdown

Service	Description	Ports	Dependencies	Status
Medical Profile Service	Manages core medical profile data with REST and gRPC endpoints	8081 (HTTP) gRPC client	PostgreSQL, Kafka, gRPC	Implemented
Medical Billing Service	Handles billing accounts with gRPC server implementation	8082 (HTTP) 9001 (gRPC)	gRPC	Implemented
Medical Analytics Service	Consumes Kafka events for analytics and reporting	8083 (HTTP)	Kafka	Implemented
API Gateway	Single entry point with JWT validation and routing	8084 (HTTP)	Auth Service	Implemented
Auth Service	JWT-based authentication and authorization	8085 (HTTP)	PostgreSQL	Implemented

Service Communication Patterns

sequenceDiagram participant Client participant Gateway as API Gateway participant Auth as Auth Service participant Profile as Medical Profile Service participant Billing as Medical Billing Service participant Kafka as Kafka participant Analytics as Medical Analytics Service Client->>Gateway: POST /auth/login {credentials} Gateway->>Auth: Forward to /login Auth-->>Gateway: JWT Token Gateway-->>Client: JWT Token Client->>Gateway: GET /api/medical-profiles (with JWT) Gateway->>Auth: Validate JWT Auth-->>Gateway: Validation Result Gateway->>Profile: Forward request Profile->>Billing: gRPC CreateBillingAccount Billing-->>Profile: Billing Account ID Profile->>Kafka: Publish MedicalProfileCreated Kafka->>Analytics: Deliver Event Profile-->>Gateway: Profile Data Gateway-->>Client: Profile Data

Key Service Features

Medical Profile Service

RESTful API with HATEOAS
gRPC client integration
Kafka event producer
DTO validation with groups
OpenAPI documentation

Auth Service

JWT token generation
BCrypt password hashing
Token validation endpoint
Role-based access control
Stateless authentication

API Gateway

Route forwarding
Global JWT validation filter
Request/response logging
Load balancing

Infrastructure Architecture

flowchart TB subgraph AWSCloud[AWS Cloud] subgraph MediCoreVPC[MediCore VPC] subgraph PublicSubnet[Public Subnet] ALB[Application Load Balancer] end subgraph PrivateSubnet[Private Subnet] subgraph ECSCluster[ECS Cluster] APIGW[API Gateway] AUTH[Auth Service] PROFILE[Profile Service] BILLING[Billing Service] ANALYTICS[Analytics Service] end subgraph AmazonRDS[Amazon RDS] AUTHDB[(Auth DB)] PROFILEDB[(Profile DB)] end subgraph AmazonMSK[Amazon MSK] KAFKA[(Kafka Cluster)] end end end CW[CloudWatch Monitoring] SM[Secrets Manager] end Internet --> ALB ALB --> APIGW APIGW --> AUTH APIGW --> PROFILE PROFILE --> |gRPC|BILLING PROFILE --> |Kafka Event|KAFKA KAFKA --> |Kafka Consume|ANALYTICS AUTH --> AUTHDB PROFILE --> PROFILEDB CW -.-> ECSCluster CW -.-> AmazonRDS CW -.-> AmazonMSK SM --> AUTHDB SM --> PROFILEDB classDef alb fill:#f3f4f6,stroke:#9ca3af; classDef ecs fill:#e0f2fe,stroke:#0ea5e9; classDef db fill:#fef3c7,stroke:#f59e0b; classDef kafka fill:#f3e8ff,stroke:#8b5cf6; classDef aws fill:#f0fdf4,stroke:#10b981; class ALB alb; class APIGW,AUTH,PROFILE,BILLING,ANALYTICS ecs; class AUTHDB,PROFILEDB db; class KAFKA kafka; class AWSCloud aws;

Infrastructure Components

Compute

ECS Fargate: Serverless container orchestration
Auto Scaling: Based on CPU/memory utilization
Task Definitions: Container specifications

Networking

VPC: Isolated network environment
Public/Private Subnets: Security zoning
ALB: Traffic distribution
Security Groups: Fine-grained access control

Data & Messaging

Amazon RDS: Managed PostgreSQL
Amazon MSK: Managed Kafka
Secrets Manager: Credential management

Local Development with LocalStack

The system supports local development using LocalStack to emulate AWS services:

flowchart TB subgraph Local[Local Development] direction TB subgraph IDE[Developer Machine] direction LR Code[Application Code] -->|"1. Deploys to"| LocalStack[LocalStack\nAWS Emulation] Tests[Test Suite] -->|"2. Invokes"| LocalStack CLI[AWS CLI] -->|"3. Configures"| LocalStack end subgraph DockerEnv[Docker Environment] APIGW[API Gateway\nContainer] AUTH[Auth Service\nContainer] PROFILE[Profile Service\nContainer] BILLING[Billing Service\nContainer] ANALYTICS[Analytics Service\nContainer] subgraph DB[Database Services] POSTGRES[PostgreSQL\nContainer] end subgraph MSG[Message Services] KAFKA[Kafka\nContainer] end end LocalStack -->|"4. Manages Containers"| DockerEnv %% Service Connections APIGW --> AUTH APIGW --> PROFILE PROFILE --> BILLING PROFILE --> KAFKA KAFKA --> ANALYTICS AUTH --> POSTGRES PROFILE --> POSTGRES end classDef dev fill:#e3f2fd,stroke:#2196f3; classDef container fill:#bbdefb,stroke:#1e88e5; classDef db fill:#fff8e1,stroke:#ffc107; classDef msg fill:#f3e5f5,stroke:#9c27b0; classDef tool fill:#e8f5e9,stroke:#66bb6a; class Local,IDE dev; class APIGW,AUTH,PROFILE,BILLING,ANALYTICS container; class DB,POSTGRES db; class MSG,KAFKA msg; class Code,Tests,CLI tool;

End-to-End Data Flow

Medical Profile Creation Flow

journey title Medical Profile Creation Workflow section Client Submit Form: 5: Client Receive Response: 5: Client section API Gateway Route Request: 3: API Gateway Validate JWT: 3: API Gateway section Auth Service Issue Token: 2: Auth Service section Medical Profile Service Process Request: 4: Profile Service Emit Event: 4: Profile Service section Medical Billing Service Create Account: 3: Billing Service section Kafka Deliver Event: 2: Kafka section Medical Analytics Service Process Event: 2: Analytics Service

Detailed Sequence Diagram

sequenceDiagram autonumber actor User participant Client participant Gateway as API Gateway participant Auth as Auth Service participant Profile as Medical Profile Service participant Billing as Medical Billing Service participant Kafka as Kafka participant Analytics as Medical Analytics Service participant ProfileDB as Profile DB participant AuthDB as Auth DB User->>Client: Submit Profile Form Client->>Gateway: POST /auth/login (credentials) Gateway->>Auth: /login Auth->>AuthDB: Validate credentials AuthDB-->>Auth: User record Auth-->>Gateway: JWT Token Gateway-->>Client: JWT Token Client->>Gateway: POST /api/medical-profiles (with JWT) Gateway->>Auth: Validate JWT Auth-->>Gateway: Validation success Gateway->>Profile: Forward create request Profile->>ProfileDB: Persist profile ProfileDB-->>Profile: Saved entity Profile->>Billing: gRPC CreateBillingAccount Billing-->>Profile: Billing account created Profile->>Kafka: Publish MedicalProfileCreated Kafka->>Analytics: Deliver event Analytics-->>Kafka: Ack Profile-->>Gateway: 201 Created Gateway-->>Client: Profile data Client->>User: Show success

Key Data Flow Characteristics

Synchronous Flows: For immediate feedback operations (login, profile creation)
Asynchronous Flows: For analytics and non-critical path operations
Eventual Consistency: Analytics may lag slightly behind primary operations
Idempotency: Critical operations designed to be safely retriable

Technology Stack

Core Technologies

Backend

Java 21 (LTS)
Spring Boot 3.5
Spring Cloud
Spring Security
gRPC
Protocol Buffers

Data & Messaging

PostgreSQL
H2 (Dev)
Apache Kafka
Spring Data JPA
Hibernate

Infrastructure

AWS CDK (Java)
Docker
ECS Fargate
Amazon RDS
Amazon MSK
LocalStack

Development Tools

Build & Test

Maven
JUnit 5
REST Assured
Testcontainers
Mockito

Documentation

SpringDoc OpenAPI
Swagger UI
Javadoc

Communication Protocols

Protocol	Use Case	Advantages	Implementation
REST (HTTP/1.1)	Client-facing APIs	Wide compatibility, easy debugging	Spring Web MVC
gRPC (HTTP/2)	Service-to-service synchronous calls	High performance, strong typing	Protobuf + gRPC Java
Kafka (TCP)	Asynchronous event streaming	Scalability, durability	Spring Kafka

Key Architectural Highlights

Security Implementation

JWT-based stateless authentication
Role-based access control
Network isolation (VPC, private subnets)
API Gateway as security perimeter

Scalability Patterns

Horizontal scaling of stateless services
Database connection pooling
Kafka consumer groups
Async non-blocking I/O

Interactive Architecture Explorer

Click to explore different communication patterns:

sequenceDiagram participant C as Client participant G as API Gateway participant P as Profile Service participant D as Profile DB C->>G: POST /api/medical-profiles (JSON) G->>P: Forward request P->>D: Save to database D-->>P: Saved entity P-->>G: 201 Created G-->>C: JSON response