Skip to content

Commit 9e1fa03

Browse files
probablyanggprobablyangg
committed
update documentation
1 parent a3d541f commit 9e1fa03

11 files changed

+250
-58
lines changed

deployment-guide.md renamed to docs/DR001_deployment-guide.md

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,20 @@
1-
# Email Queue System Deployment Guide
1+
# DR001: Email Queue System Deployment Guide
2+
3+
**Date**: 2024-12-15
4+
5+
**Status**: Accepted
6+
7+
**Context**: The application requires a robust email queue system to handle high-volume email sending without hitting rate limits. Resend API has rate limiting constraints that needed to be addressed through a Redis-based queue system.
8+
9+
**Decision**: Implement a Redis-based email queue system with deployment options for both local development and production on DigitalOcean droplets.
10+
11+
**Consequences**:
12+
- Improved email delivery reliability through rate limiting
13+
- Better scalability for high-volume email operations
14+
- Additional infrastructure complexity requiring Redis management
15+
- Deployment process now includes queue worker management
16+
17+
---
218

319
This guide explains how to deploy the Redis-based email queue system both locally and on a DigitalOcean droplet.
420

APPROVAL_ICAL_FEATURE.md renamed to docs/DR002_APPROVAL_ICAL_FEATURE.md

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,20 @@
1-
# RSVP Approval iCal Feature
1+
# DR002: RSVP Approval iCal Feature
2+
3+
**Date**: 2024-11-20
4+
5+
**Status**: Accepted
6+
7+
**Context**: Users who received RSVP approval emails had no easy way to add approved events to their calendars, requiring manual event creation and increasing friction in the user experience.
8+
9+
**Decision**: Automatically include iCal attachments in RSVP approval emails to enable one-click calendar integration for approved events.
10+
11+
**Consequences**:
12+
- Improved user experience with seamless calendar integration
13+
- Reduced manual work for users adding events to calendars
14+
- Increased complexity in email generation logic
15+
- Additional testing required for calendar compatibility across platforms
16+
17+
---
218

319
## Overview
420

CODEBASE_NOTES.md renamed to docs/DR003_Email_Queue_System.md

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,21 @@
1-
# fun lil facts
1+
# DR003: Email Queue System with Rate Limiting
2+
3+
**Date**: 2024-10-15
4+
5+
**Status**: Accepted
6+
7+
**Context**: The application was experiencing "Too many requests" errors when sending emails through Resend's API due to rate limiting constraints. The system needed a way to handle bulk email sending without hitting API limits.
8+
9+
**Decision**: Implement a global in-memory email queue system to batch and rate-limit email sending operations.
10+
11+
**Consequences**:
12+
- Eliminated rate limiting errors from Resend API
13+
- Improved reliability of email delivery
14+
- Added complexity to email sending logic
15+
- Potential for email loss during server restarts (in-memory queue)
16+
- Future migration to Redis-based queue may be needed for persistence
17+
18+
---
219

320
### Email Queue System with Rate Limiting
421

@@ -21,19 +38,3 @@ Key implementation details:
2138
- Error handling is contained within the queue processor
2239

2340
If we encounter server restarts causing email delivery issues or need to scale across multiple instances, we should consider migrating to a Redis-based queue for persistence.
24-
25-
### Default Profile Pictures (Deterministic Assignment)
26-
27-
- **File:** `src/utils/constants.ts`
28-
- **Function:** `getDefaultProfilePicture(userId)`
29-
30-
To ensure each user without a custom profile picture is consistently assigned one of the default images, we use a deterministic process based on their `userId`.
31-
32-
Instead of a simple (and potentially poorly distributed) sum-of-character-codes hash, we use the **FNV-1a (32-bit) hash algorithm**.
33-
34-
While no hash function guarantees *perfectly* uniform distribution when mapped to a smaller set via modulo, FNV-1a is designed for good distribution and exhibits a strong avalanche effect (small input changes lead to large output changes). This provides a high practical likelihood of evenly distributing the default profile pictures among users, much better than simpler methods.
35-
36-
We opted for FNV-1a over cryptographic hashes (like SHA) because:
37-
- Cryptographic-level security isn't needed.
38-
- FNV-1a is faster.
39-
- It avoids extra dependencies or complex handling.

‎docs/DR004_Default_Profile_Pictures.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# DR004: Default Profile Pictures (Deterministic Assignment)
2+
3+
**Date**: 2024-09-10
4+
5+
**Status**: Accepted
6+
7+
**Context**: Users without custom profile pictures needed to be assigned default images in a consistent and visually distributed manner. Random assignment would result in different images on each page load, creating poor user experience.
8+
9+
**Decision**: Use FNV-1a hash algorithm to deterministically assign default profile pictures based on user ID, ensuring consistent assignment while maintaining good distribution.
10+
11+
**Consequences**:
12+
- Users see the same default image consistently across sessions
13+
- Good visual distribution of default images across user base
14+
- Eliminates need for storing default image assignments in database
15+
- Slight complexity in hash algorithm implementation
16+
- Dependency on userId stability for consistent results
17+
18+
---
19+
20+
### Default Profile Pictures (Deterministic Assignment)
21+
22+
- **File:** `src/utils/constants.ts`
23+
- **Function:** `getDefaultProfilePicture(userId)`
24+
25+
To ensure each user without a custom profile picture is consistently assigned one of the default images, we use a deterministic process based on their `userId`.
26+
27+
Instead of a simple (and potentially poorly distributed) sum-of-character-codes hash, we use the **FNV-1a (32-bit) hash algorithm**.
28+
29+
While no hash function guarantees *perfectly* uniform distribution when mapped to a smaller set via modulo, FNV-1a is designed for good distribution and exhibits a strong avalanche effect (small input changes lead to large output changes). This provides a high practical likelihood of evenly distributing the default profile pictures among users, much better than simpler methods.
30+
31+
We opted for FNV-1a over cryptographic hashes (like SHA) because:
32+
- Cryptographic-level security isn't needed.
33+
- FNV-1a is faster.
34+
- It avoids extra dependencies or complex handling.

CLIENT_TESTING_GUIDE.md renamed to docs/DR005_CLIENT_TESTING_GUIDE.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,22 @@
1+
# DR005: Client-Side Testing Guide for Community-Specific Profiles
2+
3+
**Date**: 2024-12-01
4+
5+
**Status**: Accepted
6+
7+
**Context**: The community-specific profiles feature required comprehensive testing methodology to ensure proper functionality across different community subdomains and user scenarios.
8+
9+
**Decision**: Establish a detailed client-side testing guide covering browser-based testing, API validation, and user experience scenarios for community-specific profile functionality.
10+
11+
**Consequences**:
12+
- Comprehensive testing coverage for community profile features
13+
- Clear testing procedures for developers and QA
14+
- Standardized approach to validating community-specific behavior
15+
- Documentation maintenance overhead for testing procedures
16+
- Requirement for multiple test environments and subdomains
17+
18+
---
19+
120
# 🌐 Client-Side Testing Guide for Community-Specific Profiles
221

322
This guide explains how to test the community-specific profile functionality through the actual user interface in your browser.

TESTING_GUIDE.md renamed to docs/DR006_TESTING_GUIDE.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,22 @@
1+
# DR006: Community-Specific Profiles Testing Guide
2+
3+
**Date**: 2024-11-28
4+
5+
**Status**: Accepted
6+
7+
**Context**: The implementation of community-specific profiles required a comprehensive testing strategy covering automated tests, manual testing procedures, and API validation to ensure the feature works correctly across different communities.
8+
9+
**Decision**: Create a structured testing guide that covers automated testing scripts, manual testing procedures, and troubleshooting steps for community-specific profile functionality.
10+
11+
**Consequences**:
12+
- Systematic approach to testing complex multi-tenant profile features
13+
- Reduced risk of bugs in production through comprehensive test coverage
14+
- Clear documentation for developers to validate their changes
15+
- Maintenance overhead for keeping test procedures up to date
16+
- Additional complexity in test environment setup
17+
18+
---
19+
120
# Community-Specific Profiles Testing Guide
221

322
This guide explains how to test the new community-specific profile functionality.

CLERK_PROFILE_INTEGRATION.md renamed to docs/DR007_CLERK_PROFILE_INTEGRATION.md

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,22 @@
1-
# Clerk Profile Integration
1+
# DR007: Clerk Profile Integration
2+
3+
**Date**: 2024-12-10
4+
5+
**Status**: Accepted
6+
7+
**Context**: Users needed a unified, polished interface to manage their community-specific profiles. The existing custom profile management UI required significant maintenance and lacked the polish of established authentication providers.
8+
9+
**Decision**: Integrate custom community-specific profile fields into Clerk's user profile management system, providing users with a single, consistent interface for profile management while maintaining community-specific functionality.
10+
11+
**Consequences**:
12+
- Improved user experience with professional, mobile-responsive UI
13+
- Reduced maintenance overhead for custom profile management components
14+
- Better integration with authentication flow
15+
- Simplified image management through Clerk's built-in system
16+
- Dependency on Clerk's component structure and limitations
17+
- Profile images now shared across communities instead of community-specific
18+
19+
---
220

321
## Overview
422

‎docs/README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Architectural Design Records (ADRs)
2+
3+
This directory contains Architectural Design Records (ADRs) that document important technical decisions made throughout the project's development.
4+
5+
## Purpose
6+
7+
ADRs capture the context, decision, and consequences of significant architectural choices. They help:
8+
- Preserve decision-making rationale for future reference
9+
- Onboard new team members by explaining why certain approaches were chosen
10+
- Avoid revisiting settled decisions without proper context
11+
- Maintain consistency across the codebase
12+
13+
## Naming Convention
14+
15+
- Start with `DR` followed by a three-digit incremented number and an underscore
16+
- Use descriptive names that clearly indicate the decision being documented
17+
- Format: `DR###_DESCRIPTIVE_NAME.md`
18+
- Example: `DR032_Database_Migration_Strategy.md`
19+
20+
## Structure
21+
22+
Each ADR should follow this general structure:
23+
1. **Title**: Clear, concise description of the decision
24+
2. **Date**: When the decision was made (YYYY-MM-DD format)
25+
3. **Status**: Proposed, Accepted, Rejected, Deprecated, or Superseded
26+
4. **Context**: Background information and problem being solved
27+
5. **Decision**: The chosen solution and reasoning
28+
6. **Consequences**: Expected outcomes, trade-offs, and implications
29+
30+
## Current Records
31+
32+
- DR001: Deployment guide and infrastructure decisions
33+
- DR002: RSVP approval and calendar integration feature
34+
- DR003: Email queue system architecture
35+
- DR004: Default profile picture implementation
36+
- DR005: Client testing methodology
37+
- DR006: General testing guidelines
38+
- DR007: Clerk profile integration approach

0 commit comments

Comments
 (0)