- 📦 Module:
demo
- 🔢 Version:
v0.01
This module provides demonstration functionality and business application features including:
- Waitlist signup and management
- Vendor inquiry processing with email notifications
- Letter of Intent (LOI) workflow for business verification
- Google Places API integration for business location services
- Email verification and captcha validation
- Business creation and binding validation
- Survey data collection and analysis
Rate Limiting Documentation
Tests
- Core Module: Uses shared
AppState, rate limiting middleware, and error handling
- Email Module: Integrates with
EmailService for automated notifications
- External APIs: Google Places API for location services
- Security: hCaptcha integration for spam protection
- Database connections (PostgreSQL via SeaORM)
- Redis for session management and caching
- Email service configuration (SendGrid)
- Environment variables for API keys and configuration
- Rate limiting infrastructure
- Security headers and CSRF protection
- RESTful JSON API endpoints under
/api/*
- Captcha integration for form submissions
- File upload handling for business documents
- Static web page serving for demo applications
- CORS and security header management
- Standardized JSON response format for mobile consumption
- API-first design compatible with iOS HTTP clients
- Error codes and messages suitable for mobile UI feedback
- Rate limiting considerations for mobile app usage patterns
¶ Android Specific
- Compatible REST API design for Android HTTP libraries
- JSON schema validation for request/response consistency
- Mobile-friendly error handling and status codes
- Network retry-friendly endpoint design
- API Layer (
api/): HTTP request handlers for all demo endpoints
- Entity Layer (
entity/): SeaORM database models with business logic
- Web Layer (
web/): Static page handlers and web-specific routing
- Shared Layer (
shared/): Common utilities and helper functions
- Routes (
routes.rs): Router configuration and endpoint mapping
- Constants (
constants.rs): API path definitions and configuration
- Waitlist Management: Email collection with survey integration
- Vendor Inquiries: Business inquiry processing with email automation
- LOI Workflow: Multi-step business verification process
- Places Integration: Google Places autocomplete and business details
- Email Automation: Template-based email sending via SendGrid
waitlist: Email signups with referrer tracking and survey responsesvendor_interest: Vendor inquiry submissions with feature preferenceslois: Letter of Intent submissions with business verificationbusinesses: Business entities created from Google Places dataemail_verification_tokens: Secure tokens for email verification workflowsurvey_answers: Collected survey responses linked to waitlist entries
- Email sending triggers via SeaORM
after_save hooks
- Automatic business entity creation from Google Places API
- Email verification token generation and validation
- Survey data aggregation and analysis
- Session Management: User session data and temporary tokens
- Rate Limiting: Per-IP rate limit tracking across demo endpoints
- Caching: Google Places API response caching to reduce costs
- Nonce Storage: Temporary nonce values for CSRF protection
- Rate Limiting: Tiered rate limiting (strict/moderate/general) based on endpoint sensitivity
- Captcha Validation: hCaptcha integration on all public form submissions
- Email Verification: Secure token-based email verification workflow
- Input Validation: Comprehensive input sanitization and validation
- IP Tracking: Client IP detection with trusted proxy support
- Strict (1 hour): Waitlist signup, vendor inquiries, LOI submissions
- Moderate (6 seconds): LOI verification, business checks, vendor inquiries
- API (2 seconds): Google Places API calls to control costs
- General (1 second): Configuration endpoints, health checks
| Method |
Path |
Rate Limit |
Description |
| GET |
/api/health |
None |
Demo module health check |
| GET |
/api/nonce |
General |
Generate CSRF nonce token |
| GET |
/api/captcha-config |
General |
Get hCaptcha site configuration |
| Method |
Path |
Rate Limit |
Description |
| POST |
/api/waitlist |
Strict |
Submit waitlist signup with survey data |
| Method |
Path |
Rate Limit |
Description |
| POST |
/api/interest |
Strict |
Submit vendor inquiry with preferences |
| Method |
Path |
Rate Limit |
Description |
| GET |
/api/loi/start |
Moderate |
Initialize LOI process |
| POST |
/api/loi/verify |
Moderate |
Verify email and captcha |
| GET |
/api/loi/check |
Moderate |
Check business binding status |
| POST |
/api/loi/create |
Strict |
Create business from Google Places |
| POST |
/api/loi/submit |
Strict |
Submit final LOI |
| Method |
Path |
Rate Limit |
Description |
| GET |
/api/places/autocomplete |
API |
Google Places autocomplete search |
| GET |
/api/places/details |
API |
Get detailed business information |
erDiagram
waitlist ||--o{ survey_answers : has
vendor_interest ||--|| businesses : may_reference
lois ||--|| businesses : references
lois ||--|| email_verification_tokens : uses
waitlist {
uuid id PK
string email
string referrer
datetime created_at
}
vendor_interest {
uuid id PK
string name
string email
string company
text notes
boolean send_copy
json selected_apps
json additional_features
json filters
string ip_addr
string public_code
datetime created_at
}
lois {
uuid id PK
string email
uuid business_id FK
string loi_type
string status
json form_data
string public_code
datetime created_at
}
businesses {
uuid id PK
string google_place_id
string name
string address
string phone
string website
json place_details
datetime created_at
}
email_verification_tokens {
uuid id PK
string email
string token
datetime expires_at
datetime created_at
}
survey_answers {
uuid id PK
uuid waitlist_id FK
string question
string answer
datetime created_at
}
- Email Uniqueness: Waitlist and vendor interest emails are validated but not unique
- Business Binding: Each LOI must be bound to a verified Google Places business
- Email Verification: LOI workflow requires email verification via secure tokens
- Rate Limiting: All public endpoints have appropriate rate limiting
- Audit Trail: All entities include creation timestamps and IP tracking
- Vendor Interest Confirmation: Sent when
send_copy is true
- LOI Confirmation: Sent upon successful LOI submission
- Email Verification: Sent during LOI email verification process
- SendGrid API Key:
SENDGRID_API_KEY environment variable
- Sender Email:
SENDER_EMAIL environment variable
- Template System: Uses structured email templates with variable substitution
- Error Handling: Email failures are logged but don't block database operations
- Purpose: Business location search and verification
- Endpoints: Autocomplete and Place Details
- Caching: Responses cached in Redis to reduce API costs
- Rate Limiting: Controlled via API rate limiting tier (30 requests/minute)
- Configuration: Requires
GOOGLE_PLACES_API_KEY environment variable
- Purpose: Spam protection on public forms
- Configuration:
HCAPTCHA_SITEKEY and HCAPTCHA_SECRET environment variables
- Validation: Server-side verification for all form submissions
- Error Handling: Captcha failures return specific error codes
¶ Error Handling
- 400 Bad Request: Invalid input data or missing required fields
- 403 Forbidden: Captcha validation failed or access denied
- 429 Too Many Requests: Rate limit exceeded
- 500 Internal Server Error: Database or email service failures
- 502 Bad Gateway: External API failures (Google Places, hCaptcha)
{
"error": "error_code",
"message": "Human readable error description"
}
email_invalid: Email format validation failedcaptcha_required: Missing captcha tokencaptcha_failed: Captcha verification failedrate_limit_exceeded: Too many requestsdb_error: Database operation failedbusiness_not_found: Referenced business doesn't exist
# Database
DB_GENERIC_USER=demo_user
DB_GENERIC_PASSWORD=demo_password
DB_IP=localhost
DB_PORT=5432
DB_NAME=server_db
# Redis
REDIS_IP=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
# Email Service
SENDGRID_API_KEY=your_sendgrid_api_key
SENDER_EMAIL=noreply@yourdomain.com
# External APIs
GOOGLE_PLACES_API_KEY=your_google_places_key
HCAPTCHA_SITEKEY=your_hcaptcha_site_key
HCAPTCHA_SECRET=your_hcaptcha_secret
# Security
NONCE_NAMESPACE=demo_nonce
NONCE_TTL_SECS=300
TRUSTED_PROXY_CIDRS=127.0.0.1/32,::1/128
- Ensure all environment variables are properly set
- Database migrations must be run before startup
- Redis must be accessible and configured
- External API keys must be valid and have appropriate quotas
- Rate limiting requires Redi