374 lines
12 KiB
Markdown
374 lines
12 KiB
Markdown
# GUIDE
|
||
This document outlines the technical architecture and organization of the project. It details the high-level architectural design, the rationale behind the codebase structure, descriptions of key functional components, and illustrates primary data flows within the system. The aim is to provide a clear and comprehensive guide for developers and architects involved with the project.
|
||
# FORMAT
|
||
## Title: [Application/Website Name]
|
||
app_ver: [app_ver]
|
||
doc_ver: [doc_ver]
|
||
## 1. Architecture Overview
|
||
[Explanation of the overall architecture model (e.g., Microservices, Monolithic, Layered). Brief description of the main parts of the system and their high-level relationships. Can include a high-level architecture diagram (if available).]
|
||
## 2. Project Structure
|
||
[Brief overview of how the directory structure organizes the codebase and the reasoning behind this organization.]
|
||
### Directory Tree
|
||
A/
|
||
├── B/
|
||
│ ├── C/ # [Brief explanation]
|
||
│ │ ├── C1/ # [Brief explanation]
|
||
│ │ └── C2/ # [Brief explanation]
|
||
│ ├── D/ # [Brief explanation]
|
||
│ │ ├── D1/ # [Brief explanation]
|
||
### Structure Explanation
|
||
[More detailed explanation of the roles and responsibilities of the main layers and directories. Why this structure was chosen.]
|
||
## 3. Key Components
|
||
### [Numerical order]. [Component Name]
|
||
* **Description:** [Detailed description of the component's function and responsibilities.]
|
||
* **Location in Directory Tree (if relevant):** [Directory path]
|
||
* **Dependencies:** [List of components this component depends on]
|
||
* **Interactions with Other Components:** [Description of how this component interacts with other parts of the system.]
|
||
## 4. Main Data Flow
|
||
[Description of the most important data flows in the system, such as user creation flow, order processing flow. Can use a Mermaid diagram for visualization.]
|
||
```
|
||
[mermaid flow chart here]
|
||
```
|
||
|
||
---
|
||
# CONTENT
|
||
|
||
## Title: ZEE Quiz Application
|
||
app_ver: 1.0.0
|
||
doc_ver: A1
|
||
|
||
## 1. Architecture Overview
|
||
|
||
### 1.1. System Architecture
|
||
|
||
The ZEE Quiz Application follows a **modular monolith** architecture with **Domain-Driven Design (DDD)** principles. This approach provides the right balance between maintainability and development velocity while keeping the system simple to deploy and operate.
|
||
|
||
**Key Architectural Principles:**
|
||
- **Domain-Driven Design (DDD)** for clear domain boundaries
|
||
- **Clean Architecture** for separation of concerns
|
||
- **Container-First** design for cloud-native deployment
|
||
|
||
### 1.2. High-Level Architecture
|
||
|
||
```mermaid
|
||
graph TD
|
||
Client[Web Client] --> HTTP[HTTP Transport Layer]
|
||
HTTP --> Handler[Request Handlers]
|
||
Handler --> Service[Business Services]
|
||
|
||
subgraph Internal Resources
|
||
Service --> User[User Resource]
|
||
Service --> Role[Role Resource]
|
||
end
|
||
|
||
subgraph Infrastructure
|
||
User --> DB[(PostgreSQL)]
|
||
Role --> DB
|
||
User --> Cache[(Redis)]
|
||
Service --> Logger[Logger]
|
||
end
|
||
|
||
subgraph Helpers
|
||
Handler --> Config[Config Helper]
|
||
Service --> Feature[Feature Flags]
|
||
DB --> DBUtil[Database Utils]
|
||
end
|
||
```
|
||
|
||
**Component Responsibilities:**
|
||
|
||
1. **Transport Layer**
|
||
- HTTP request/response handling
|
||
- Route management
|
||
- Middleware (auth, logging, etc.)
|
||
- DTO validation
|
||
|
||
2. **Business Services**
|
||
- Core business logic implementation
|
||
- Transaction management
|
||
- Resource coordination
|
||
- Event handling
|
||
|
||
3. **Internal Resources**
|
||
- User management
|
||
- Role and permissions
|
||
- Domain logic encapsulation
|
||
|
||
4. **Infrastructure**
|
||
- PostgreSQL for persistent storage
|
||
- Redis for caching
|
||
- Structured logging
|
||
|
||
5. **Helper Utilities**
|
||
- Configuration management
|
||
- Database utilities
|
||
- Feature flag management
|
||
- Common helper functions
|
||
|
||
## 2. Project Structure
|
||
|
||
### 2.1. Directory Structure
|
||
|
||
```
|
||
zee/
|
||
├── cmd/ # Application entry points
|
||
│ └── app/ # Main application server
|
||
│
|
||
├── configs/ # Configuration files
|
||
│
|
||
├── docs/ # Documentation files
|
||
│
|
||
├── internal/ # Private application code
|
||
│ ├── adapter/ # External adapters
|
||
│ │ └── postgres/ # PostgreSQL adapter
|
||
│ ├── helper/ # Helper utilities
|
||
│ │ ├── config/ # Configuration helpers
|
||
│ │ ├── database/ # Database utilities
|
||
│ │ ├── feature/ # Feature flags
|
||
│ │ └── logger/ # Logging utilities
|
||
│ ├── pkg/ # Internal packages
|
||
│ │ └── lifecycle/ # Application lifecycle
|
||
│ ├── resource/ # Domain resources
|
||
│ │ ├── role/ # Role management
|
||
│ │ └── user/ # User management
|
||
│ ├── service/ # Business services
|
||
│ └── transport/ # Transport layer
|
||
│ └── http/ # HTTP handlers
|
||
│ ├── dto/ # Data transfer objects
|
||
│ ├── handler/ # Request handlers
|
||
│ └── middleware/ # HTTP middleware
|
||
│
|
||
├── migrations/ # Database migrations
|
||
│
|
||
└── templates/ # Template files
|
||
│ ├── interfaces/ # Interface adapters
|
||
│ │ ├── http/ # HTTP handlers
|
||
│ │ │ ├── v1/ # API v1 routes
|
||
│ │ │ └── middleware # HTTP middleware
|
||
│ │ └── repository/ # Repository implementations
|
||
│ │
|
||
│ └── pkg/ # Shared packages
|
||
│ ├── auth/ # Authentication
|
||
│ ├── logger/ # Logging
|
||
│ └── validator/ # Input validation
|
||
│
|
||
├── pkg/ # Public packages
|
||
│ ├── errors/ # Common errors
|
||
│ └── uuid/ # UUID utilities
|
||
│
|
||
├── migrations/ # Database migrations
|
||
├── web/ # Frontend assets
|
||
├── configs/ # Configuration files
|
||
├── scripts/ # Utility scripts
|
||
├── .github/ # GitHub workflows
|
||
├── docs/ # Documentation
|
||
├── go.mod # Go module definition
|
||
└── Makefile # Common tasks
|
||
```
|
||
|
||
### 2.2. Structure Explanation
|
||
|
||
- **cmd/api**: Contains the application's entry point and server setup
|
||
- **internal/domain**: Core domain models and business logic (DDD)
|
||
- **internal/application**: Application services and use cases
|
||
- **internal/interfaces**: Adapters for external communication (HTTP, repositories)
|
||
- **internal/pkg**: Shared infrastructure code
|
||
- **pkg**: Public reusable packages
|
||
- **migrations**: Database schema migrations
|
||
- **web**: Frontend assets and templates
|
||
- **configs**: Configuration files for different environments
|
||
|
||
## 3. Key Components
|
||
|
||
### 3.1. API Gateway
|
||
* **Description**: Single entry point for all client requests
|
||
* **Location**: `internal/interfaces/http`
|
||
* **Dependencies**: Application services, Authentication, Rate limiting
|
||
* **Responsibilities**:
|
||
- Request/response handling
|
||
- Authentication & Authorization
|
||
- Request validation
|
||
- Rate limiting
|
||
- CORS handling
|
||
|
||
### 3.2. User Management
|
||
* **Description**: Handles user registration, authentication, and profile management
|
||
* **Location**: `internal/domain/user`, `internal/application/commands/user`
|
||
* **Dependencies**: JWT, Password hashing, Email service
|
||
* **Key Features**:
|
||
- User registration with email verification
|
||
- JWT-based authentication
|
||
- Profile management
|
||
- Role-based access control
|
||
|
||
### 3.3. Quiz Engine
|
||
* **Description**: Core quiz functionality
|
||
* **Location**: `internal/domain/quiz`, `internal/application/commands/quiz`
|
||
* **Dependencies**: Question repository, User repository
|
||
* **Features**:
|
||
- Question management
|
||
- Quiz session handling
|
||
- Timer management
|
||
- Answer validation
|
||
|
||
### 3.4. Result Processing
|
||
* **Description**: Handles quiz results and scoring
|
||
* **Location**: `internal/domain/result`, `internal/application/queries/result`
|
||
* **Dependencies**: Quiz repository, User repository
|
||
* **Features**:
|
||
- Score calculation
|
||
- Leaderboard generation
|
||
- Result caching
|
||
- Analytics
|
||
|
||
## 4. Main Data Flows
|
||
|
||
### 4.1. User Registration Flow
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as Client
|
||
participant A as API Gateway
|
||
participant U as User Service
|
||
participant D as Database
|
||
participant E as Email Service
|
||
|
||
C->>A: POST /api/v1/register
|
||
A->>U: RegisterUserCommand
|
||
U->>D: Begin Transaction
|
||
U->>D: Check if email exists
|
||
U->>D: Create user
|
||
U->>E: Send verification email
|
||
U->>D: Commit Transaction
|
||
U-->>A: User created
|
||
A-->>C: 201 Created
|
||
```
|
||
|
||
### 4.2. Quiz Submission Flow
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as Client
|
||
participant A as API Gateway
|
||
participant Q as Quiz Service
|
||
participant R as Result Service
|
||
participant D as Database
|
||
participant K as Cache (Redis)
|
||
|
||
C->>A: POST /api/v1/quizzes/submit
|
||
A->>Q: SubmitQuizCommand
|
||
Q->>D: Load quiz session
|
||
Q->>Q: Validate answers
|
||
Q->>R: CalculateScoreCommand
|
||
R->>D: Save results
|
||
R->>K: Update leaderboard
|
||
R-->>Q: Score calculated
|
||
Q-->>A: Quiz result
|
||
A-->>C: 200 OK with result
|
||
```
|
||
|
||
## 5. Technology Stack
|
||
|
||
### 5.1. Backend
|
||
- **Language**: Go 1.24.3
|
||
- **Web Framework**: Gin-Gonic Router
|
||
- **ORM**: GORM
|
||
- **Migrations**: GORM Migrate
|
||
- **Validation**: go-playground/validator
|
||
- **Logging**: zap
|
||
- **Configuration**: viper
|
||
- **Testing**: testify, gomock
|
||
|
||
### 5.2. Frontend
|
||
- **HTMX** for dynamic UI updates
|
||
- **TailwindCSS** for styling
|
||
- **Alpine.js** for client-side interactions
|
||
- **HTMX Extensions** for advanced functionality
|
||
|
||
### 5.3. Infrastructure
|
||
- **Containerization**: Docker
|
||
- **Orchestration**: Docker Compose (local), Kubernetes (production)
|
||
- **Database**: PostgreSQL 14
|
||
- **Caching**: Redis
|
||
- **Storage**: AWS S3
|
||
- **CI/CD**: Gitea Actions
|
||
- **Monitoring**: Prometheus, Grafana
|
||
- **Logging**: ELK Stack
|
||
|
||
## 6. Deployment Architecture
|
||
|
||
### 6.1. Development Environment
|
||
- Local Docker Compose setup
|
||
- Hot-reload for development
|
||
- Development database with sample data
|
||
|
||
### 6.2. Production Environment
|
||
- Container orchestration with Kubernetes
|
||
- Auto-scaling based on load
|
||
- Multi-AZ deployment for high availability
|
||
- Automated backups and disaster recovery
|
||
|
||
## 7. Security Considerations
|
||
|
||
### 7.1. Authentication & Authorization
|
||
- JWT-based authentication
|
||
- Role-based access control (RBAC)
|
||
- Secure password hashing (bcrypt)
|
||
- Rate limiting
|
||
- CORS policy
|
||
|
||
### 7.2. Data Protection
|
||
- TLS 1.3 for all communications
|
||
- Sensitive data encryption at rest
|
||
- Regular security audits
|
||
- GDPR compliance
|
||
|
||
## 8. Performance Considerations
|
||
|
||
### 8.1. Caching Strategy
|
||
- Redis for frequently accessed data
|
||
- HTTP caching headers
|
||
- Database query result caching
|
||
|
||
### 8.2. Database Optimization
|
||
- Proper indexing
|
||
- Query optimization
|
||
- Connection pooling
|
||
- Read replicas for scaling reads
|
||
|
||
## 9. Monitoring & Observability
|
||
|
||
### 9.1. Metrics
|
||
- Request/response times
|
||
- Error rates
|
||
- Database query performance
|
||
- System resource usage
|
||
|
||
### 9.2. Logging
|
||
- Structured logging with correlation IDs
|
||
- Log levels (debug, info, warn, error)
|
||
- Centralized log management
|
||
|
||
### 9.3. Alerting
|
||
- Error rate thresholds
|
||
- Response time thresholds
|
||
- System resource alerts
|
||
- Business metrics alerts
|
||
|
||
## 10. Future Considerations
|
||
|
||
### 10.1. Scalability
|
||
- Sharding for database scaling
|
||
- Event sourcing for audit trail
|
||
- CQRS for read/write scaling
|
||
|
||
### 10.2. Features
|
||
- Real-time leaderboard updates
|
||
- Social sharing
|
||
- Offline quiz support
|
||
- Mobile app integration
|
||
|
||
---
|
||
|
||
*Last Updated: 2025-06-06*
|
||
*Document Version: A1* |