zee-solution/docs/adapter.md

# GUIDE
Document details the various connections established by the application. It outlines integrations with external APIs, connections to essential backend services (like queues or storage), and the communication pathways between internal modules. The purpose is to provide a clear map of the application's dependencies and interaction points, aiding in development, troubleshooting, and understanding system dependencies.
# FORMAT
## Title: [Application/Website Name]
app_ver: [app_ver]
doc_ver: [doc_ver]
## API Connections
### [Numerical order].[API Name]
**Purpose:** [Brief description of the connection purpose]
**Type:** [REST/GraphQL/...]
**Base URL:** [Base URL of the API]
**Version**: [API Version]
**Key Endpoints:**
- [Endpoint 1]: [Brief description of function]
- [Endpoint 2]: [Brief description of function]
**Authentication:** [Authentication method.]
**Adapter Module:** [Module path]
**Notes:** [Key points about integration, errors, limitations, specified error handling requirements]
## Service Connections
### [Numerical order].[Service Name]
**Purpose:** [Brief description of the connection purpose]
**Type:** [Queue/Log/Storage/...]
**Connection Details:** [Address, protocol (e.g., `kafka://...`, `redis://...`), Added message routing strategies]
**Authentication/Authorization:** [Authentication/authorization method]
**Interaction Module:** [Module path]
**Notes:** [Key points about reliability, performance, retention policies, encryption]
## Internal Connections
### [Numerical order].[Module A] - [Module B]
**Purpose:** [Brief description of the interaction purpose]
**Interaction Type:** [n-way connection, Direct function call, Message Bus (channel name), Event (event name)]
**Details:** [Important function/event names, message format (if needed), event schemas and delivery guarantees]
**Notes:** [Key points about data consistency, error handling]

# CONTENT
---
# ZEE Quiz Application Adapters
app_ver: 1.0.0
doc_ver: A1

## API Connections

### 1. Auth0 Authentication API
**Purpose:** Handle user authentication and authorization
**Type:** OAuth 2.0 / OIDC
**Base URL:** `https://{tenant}.auth0.com`
**Version**: v2
**Key Endpoints:**
- `/authorize`: Handle user login
- `/oauth/token`: Get access tokens
- `/userinfo`: Retrieve user profile
- `/dbconnections`: Manage database connections
**Authentication:** JWT Bearer Token
**Adapter Module:** `/src/adapters/auth/auth0.adapter.ts`
**Notes:** 
- Implements refresh token rotation
- Rate limited to 1000 requests per minute
- All tokens have a 24-hour expiration

### 2. SendGrid Email API
**Purpose:** Send transactional emails (verification, password reset, etc.)
**Type:** REST
**Base URL:** `https://api.sendgrid.com/v3`
**Version**: v3
**Key Endpoints:**
- `/mail/send`: Send emails
- `/templates`: Manage email templates
**Authentication:** API Key
**Adapter Module:** `/src/adapters/email/sendgrid.adapter.ts`
**Notes:**
- Daily quota: 100,000 emails
- Supports dynamic templates with Handlebars
- Webhook integration for delivery status

## Service Connections

### 1. Redis Cache
**Purpose:** Caching and session storage
**Type:** In-memory Data Store
**Connection Details:** 
- Protocol: `redis://{host}:6379`
- Database: 0 (Sessions), 1 (Cache)
- TLS: Enabled
**Authentication:** Password-based
**Interaction Module:** `/src/infrastructure/cache/redis.client.ts`
**Notes:**
- 30-minute TTL for session data
- LRU eviction policy
- Cluster mode enabled for high availability

### 2. PostgreSQL Database
**Purpose:** Primary data storage
**Type:** Relational Database
**Connection Details:**
- Protocol: `postgresql://{user}:{password}@{host}:5432/zee_quiz`
- Pool Size: 20 connections
- SSL: Enforced
**Authentication:** Username/Password with SCRAM-SHA-256
**Interaction Module:** `/src/infrastructure/database/prisma.service.ts`
**Notes:**
- Connection pooling enabled
- Read replicas for scaling
- Daily backups with 30-day retention

### 3. AWS S3 Storage
**Purpose:** File storage for user uploads and media
**Type:** Object Storage
**Connection Details:**
- Endpoint: `https://s3.{region}.amazonaws.com`
- Bucket: `zee-quiz-{environment}`
- Region: ap-southeast-1
**Authentication:** AWS IAM Role
**Interaction Module:** `/src/adapters/storage/s3.adapter.ts`
**Notes:**
- Private bucket with signed URLs
- Lifecycle policy for temp files (7-day expiration)
- CORS configured for web client access

## Internal Connections

### 1. API Gateway → User Service
**Purpose:** Handle user-related operations
**Interaction Type:** gRPC
**Details:**
- Service: `user.UserService`
- Methods: 
  - `GetUserProfile(userId: string) → User`
  - `UpdateProfile(UpdateProfileRequest) → User`
  - `SearchUsers(SearchUsersRequest) → UserList`
**Notes:**
- Request/response logging enabled
- Circuit breaker with 3 retries
- 5-second timeout

### 2. Quiz Service → Question Service
**Purpose:** Retrieve and manage quiz questions
**Interaction Type:** GraphQL
**Details:**
- Endpoint: `http://question-service/graphql`
- Queries:
  - `getQuestions(quizId: ID!): [Question!]!`
  - `validateAnswer(questionId: ID!, answer: String!): Boolean!`
**Notes:**
- Persistent queries for performance
- Batched requests where possible
- 3-second timeout

### 3. Notification Service → WebSocket Gateway
**Purpose:** Real-time notifications
**Interaction Type:** WebSocket Events
**Details:**
- Event: `notification:new`
- Payload: 
  ```typescript
  {
    userId: string;
    type: 'QUIZ_COMPLETED' | 'NEW_MESSAGE' | 'SYSTEM';
    message: string;
    data?: Record<string, any>;
    timestamp: string;
  }
  ```
**Notes:**
- Acknowledgment required
- Automatic reconnection with backoff
- Message queuing for offline users

### 4. Analytics Service → Data Pipeline
**Purpose:** Stream quiz attempt data for analysis
**Interaction Type:** Message Queue (Kafka)
**Details:**
- Topic: `quiz.attempts`
- Schema:
  ```avro
  {
    "type": "record",
    "name": "QuizAttempt",
    "fields": [
      {"name": "attemptId", "type": "string"},
      {"name": "userId", "type": "string"},
      {"name": "quizId", "type": "string"},
      {"name": "score", "type": "float"},
      {"name": "duration", "type": "int"},
      {"name": "timestamp", "type": "string", "logicalType": "timestamp-millis"}
    ]
  }
  ```
**Notes:**
- Exactly-once delivery semantics
- 7-day retention period
- Schema evolution enabled

---
*Last Updated: 2025-06-06*
*Next Review: 2025-07-01*