106 lines
13 KiB
Markdown
106 lines
13 KiB
Markdown
Alright, we've covered a lot of ground and defined the core aspects of the Matchmaking Microsite project. Based on our discussions, here is the foundational architectural design documentation, presented in the structured format you requested.
|
|
|
|
---
|
|
|
|
**Matchmaking Microsite - Foundational Architectural Design**
|
|
|
|
**Version:** 1.0
|
|
**Date:** April 26, 2025
|
|
|
|
**1. Project Overview**
|
|
|
|
* **Platform Purpose and Vision:** To create an engaging online experience for a specific matchmaking campaign ("Team Ngọt Ngào và Thanh Dịu"), allowing users to register, be intelligently matched based on defined criteria, and discover potential connections within the campaign's framework.
|
|
* **Key Functional Scope (Key Capabilities):**
|
|
* User registration with personal details, preferences, and photo upload[cite: 3, 4, 5, 6, 7].
|
|
* Automated matching based on criteria: Team choice, Hobbies, Zodiac Sign, Age difference (+/- 5 years), Gender preference[cite: 7, 8, 9, 10, 11].
|
|
* Secure access to match results via unique code or link[cite: 19, 20].
|
|
* Display of 3 potential matches with limited initial information, revealing more details upon user selection[cite: 21, 22].
|
|
* Email notifications for registration confirmation, result availability, and lucky draw winners[cite: 12, 18, 19, 24].
|
|
* Administrative dashboard for monitoring, campaign management (triggering matching), and gift management.
|
|
* Reporting on key metrics (total users, team distribution, match selection count)[cite: 26, 27].
|
|
* **Primary Users/Roles and Core Value Delivered:**
|
|
* **Participants (End Users):** Individuals seeking a match within the campaign. Value: A fun, easy way to participate, discover potentially compatible individuals based on shared interests and campaign themes, and potentially win prizes.
|
|
* **Campaign Administrators:** Staff managing the campaign. Value: A tool to automate the matching process, monitor participation, manage campaign phases, and handle winner notifications efficiently.
|
|
|
|
**2. System Architecture Overview**
|
|
|
|
* **Core Architectural Patterns:**
|
|
* **Domain-Driven Design (DDD):** Focusing on the core domain (matchmaking, profiles, results) using Aggregates (`Resource` components) to encapsulate state and behavior.
|
|
* **Event-Driven (Implicit):** System workflows (`Transaction` components) react to events (e.g., User Registered, Matching Complete, Match Selected) to trigger subsequent actions like notifications or state updates. Events will primarily orchestrate Sagas/Transactions internally.
|
|
* **Data Oriented Programming Concepts:** Structuring logic around data transformations (e.g., DOB to Zodiac[cite: 4], Profile data to Match Criteria, Match Results to Display DTOs). Clear separation of data (Resources) and processing logic (Transactions, Helpers).
|
|
* **Core Components:**
|
|
* **`Resource`**: Represents core DDD Aggregates (`Profile`, `MatchOutcome`, `GiftAllocation`, `Gift`). Manages state, data integrity, and core domain logic related to these entities.
|
|
* **`Transaction`**: Orchestrates business workflows (Sagas/Process Managers) involving multiple steps or Resources (e.g., `UserRegistrationTransaction`, `MatchingTransaction`, `ResultNotificationTransaction`). Ensures process completion or compensation.
|
|
* **`Adapter`**: Handles communication with external systems/infrastructure (e.g., `PersistenceAdapter` for PostgreSQL, `EmailAdapter`, `FileStorageAdapter`). Isolates core logic from external details.
|
|
* **`Helper`**: Provides shared, stateless utility functions (e.g., configuration loading, logging, common validation, date/time utils).
|
|
* **`UIUX`**: Frontend interface layer. Given the preference, this will primarily involve server-side rendering of HTML fragments via Go templates interacting with HTMX, alongside a separate Admin Dashboard UI (potentially using more client-side JS).
|
|
* **Proposed Technology Stack:**
|
|
* **Backend:** Go (Performance, concurrency for potential load, strong typing).
|
|
* **Frontend:** HTMX (Primary user interface, server-rendered HTML fragments), potentially minimal JavaScript (Alpine.js/Hyperscript) where needed. Admin Dashboard may utilize more JS.
|
|
* **Database:** PostgreSQL (Reliable relational storage, potential for JSONB for flexible fields like hobbies if needed, though structured preferred for filtering criteria). Use a managed cloud service (e.g., RDS, Cloud SQL).
|
|
* **Workflow/Rule Engine:** *Considered* for the `MatchingTransaction` if the filtering logic [cite: 9, 10, 11] becomes highly complex or needs frequent changes, allowing externalization of rules. Otherwise, implement directly in Go.
|
|
* **Containerization:** Docker (Consistent environments, ease of deployment).
|
|
* **Hosting:** Cloud Platform (AWS/GCP/Azure - Scalability, managed services).
|
|
* *(Rationale):* This stack offers good performance (Go), robust data storage (Postgres), a simplified frontend approach (HTMX), and leverages cloud infrastructure for scalability and manageability.
|
|
* **High-Level Data/Event Flow:**
|
|
1. User submits registration form (UIUX/HTMX -> API Endpoint).
|
|
2. `UserRegistrationTransaction` creates `Profile` (Resource), saves via `PersistenceAdapter`, sends email via `EmailAdapter`.
|
|
3. Admin/Scheduler triggers Matching (Admin UI -> API Endpoint or Scheduled Job).
|
|
4. `MatchingTransaction` reads `Profiles`, applies logic, creates `MatchOutcome`s, saves via `PersistenceAdapter`.
|
|
5. `ResultNotificationTransaction` reads `Profile`/`MatchOutcome`, sends email via `EmailAdapter`, updates `Profile` status via `PersistenceAdapter`.
|
|
6. User accesses results (UIUX/HTMX -> API Endpoint). Backend verifies access, fetches `MatchOutcome`, renders HTML fragment with limited match data.
|
|
7. User selects/declines (UIUX/HTMX -> API Endpoint). `MatchSelectionTransaction` updates `MatchOutcome`/`Profile` via `PersistenceAdapter`. Backend renders updated HTML fragment (e.g., showing full details or end message).
|
|
* **Key Non-Functional Requirements and Approach:**
|
|
* **Scalability:** Handle 20k+ users[cite: 27]. Approach: Asynchronous/batch processing for `MatchingTransaction` and potentially bulk email notifications; efficient database queries with appropriate indexing; stateless backend services suitable for horizontal scaling behind a load balancer.
|
|
* **Security:** Protect user PII. Approach: Secure admin login (e.g., JWT); secure user result access via unique, non-guessable codes/links; limit PII exposure until explicit selection[cite: 22]; standard web security practices (input validation, HTTPS); secure file storage policies.
|
|
* **Flexibility/Configurability:** Campaign details might change in future iterations. Approach: Utilize the `Campaign` Resource to store configurable parameters (texts, dates, potentially aspects of matching logic if externalized).
|
|
* **Approach to Data Consistency:** Primarily handled by ACID properties of PostgreSQL for single Resource operations. Transactions/Sagas (`MatchingTransaction`, etc.) ensure operational consistency across steps, though complex compensation logic is likely minimal for this scope unless distributed systems become involved (unlikely here).
|
|
|
|
**3. Internal Structuring Approach (U-Hierarchy Confirmation)**
|
|
|
|
* **Confirmation:** We will adopt the `ubit`, `ubrick`, `ublock`, `ubundle` hierarchy as defined.
|
|
* **Usage Explanation:** This hierarchy will structure the source code and logical components *within* the core architectural components (`Resource`, `Transaction`, `Adapter`, `Helper`, `UIUX`-backend rendering logic) to promote modularity, testability, and reusability.
|
|
* **`ubits`** (e.g., individual validation functions, type definitions, constants) will form the smallest building blocks.
|
|
* **`ubricks`** (e.g., `ProfileDataValidation` module, `ZodiacCalculator`, `PostgresConnectionManager`) will group related `ubits` into cohesive units.
|
|
* **`ublocks`** (e.g., the entire `resource/profile` package, the `adapter/postgres` package, a specific `transaction/registration` saga implementation) will compose `ubricks` to manage distinct pieces of functionality.
|
|
* **`ubundles`** (e.g., the "User Registration" feature, "Admin Reporting") represent complete features achieved through the collaboration of multiple `ublocks` across different core components.
|
|
* The proposed directory structure reflects this, with package directories representing `ublocks` and internal files/structs representing `ubricks` and `ubits`.
|
|
|
|
**4. High-Level Feature Roadmap / Phasing**
|
|
|
|
* **Setup Phase (Phase 0 - Foundation):**
|
|
* Infrastructure Setup: Cloud environment provisioning, VPC, security groups.
|
|
* CI/CD Pipeline Setup: Basic pipeline for build, test, deploy.
|
|
* Database Provisioning: Setup managed PostgreSQL instance.
|
|
* Core Component Setup: Initialize Go project structure, setup logging, configuration management, base API framework, core DB connection logic (`PersistenceAdapter` base).
|
|
* **Phase 1: Core User Experience & Matching:**
|
|
* Capabilities: Homepage display, User Registration (Form + Photo Upload), Backend Matching Logic (Batch), Result Access (Code/Link), Result Display (3 limited profiles), Match Selection/Declination, Basic Email Notifications (Confirmation, Results).
|
|
* Components Involved: `UIUX` (HTMX Views), `API` (Endpoints), `Transaction` (Registration, Matching, Result Notification, Selection), `Resource` (`Profile`, `MatchOutcome`), `Adapter` (Postgres, Email, FileStorage), `Helper`.
|
|
* **Phase 2: Admin Dashboard & Management:**
|
|
* Capabilities: Admin Login, Reporting Dashboard (User stats, Team stats), Campaign Management (Trigger Matching, Open/Close Registration), Basic Gift Definition UI.
|
|
* Components Involved: `UIUX` (Admin Views), `API` (Admin Endpoints), `Transaction` (Admin triggers), `Resource` (`Gift`), `Adapter` (Postgres).
|
|
* **Phase 3: Gift Giveaway & Refinements:**
|
|
* Capabilities: Lucky Draw/Winner Allocation logic, Winner Email Notification, Gift Allocation Tracking (Admin). Potential UI refinements based on initial feedback.
|
|
* Components Involved: `Transaction` (Gift Allocation, Gift Notification), `Resource` (`GiftAllocation`), `Adapter` (Email, Postgres), `API` (Admin Endpoints).
|
|
|
|
**5. Key Interfaces / Interaction Points**
|
|
|
|
* **User Microsite (via HTMX):** The primary interface for participants, rendered server-side by the Go backend, enabling registration, result access, and interaction.
|
|
* **Admin Dashboard:** A separate web interface for administrators to monitor the campaign, manage phases, view reports, and manage gifts. Likely requires more client-side JavaScript interaction with JSON APIs.
|
|
* **Email Notifications:** System-generated emails sent to users for key events (registration, results, winning prizes) via an external Email Service (`EmailAdapter`).
|
|
* **(Internal) File Storage API:** Interface used by the backend (`FileStorageAdapter`) to interact with the chosen file storage service (e.g., S3 API) for photo uploads/retrieval.
|
|
* **(Internal) Database Interface:** Interface used by the `PersistenceAdapter` to interact with the PostgreSQL database.
|
|
|
|
**6. System-Wide Error Handling Strategy**
|
|
|
|
* **Detection & Categorization:** Errors will be detected at various layers (API validation, Transaction logic, Adapter communication). Errors will be categorized (e.g., user input error, resource not found, external service failure, internal server error).
|
|
* **Propagation:** Errors from lower layers (Adapters, Resources) will be propagated up to the calling Transaction or API Handler, potentially wrapped for context.
|
|
* **Logging:** All significant errors (especially non-user correctable ones) will be logged centrally with structured information (timestamp, error type, stack trace if applicable, request context). A dedicated `Logging` Helper will be used.
|
|
* **State Consistency:** Database transactions within the `PersistenceAdapter` will be used to ensure atomic updates to Resources, maintaining consistency in case of errors during writes. Sagas (`Transaction` components) will handle logical consistency across multiple steps (though complex compensation is expected to be minimal).
|
|
* **Communication:**
|
|
* *To Users (via HTMX/API):* User input errors will result in user-friendly messages, potentially rendered directly into HTML fragments by the backend. Generic messages will be used for unexpected server errors to avoid exposing internal details. Standard HTTP status codes will be used (e.g., 400 for bad input, 404 for not found, 500 for server error).
|
|
* *To Admins:* Detailed error information will be available in logs. The Admin Dashboard might display specific error summaries or alerts for critical issues.
|
|
|
|
---
|
|
|
|
This document provides the high-level architectural blueprint for the Matchmaking Microsite project based on our collaborative design process. |