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:

  {
    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:

  {
    "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