linting docs + some fixes go claude and gemini
All checks were successful
Deploy to Test Environment / deploy-to-test (push) Successful in 16m0s
All checks were successful
Deploy to Test Environment / deploy-to-test (push) Successful in 16m0s
This commit is contained in:
@@ -79,7 +79,8 @@
|
||||
"Bash(npm run lint)",
|
||||
"Bash(npm run typecheck:*)",
|
||||
"Bash(npm run type-check:*)",
|
||||
"Bash(npm run test:unit:*)"
|
||||
"Bash(npm run test:unit:*)",
|
||||
"mcp__filesystem__move_file"
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
110
AUTHENTICATION.md
Normal file
110
AUTHENTICATION.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# Authentication Setup
|
||||
|
||||
Flyer Crawler supports OAuth authentication via Google and GitHub. This guide walks through configuring both providers.
|
||||
|
||||
---
|
||||
|
||||
## Google OAuth
|
||||
|
||||
### Step 1: Create OAuth Credentials
|
||||
|
||||
1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
|
||||
2. Create a new project (or select an existing one)
|
||||
3. Navigate to **APIs & Services > Credentials**
|
||||
4. Click **Create Credentials > OAuth client ID**
|
||||
5. Select **Web application** as the application type
|
||||
|
||||
### Step 2: Configure Authorized Redirect URIs
|
||||
|
||||
Add the callback URL where Google will redirect users after authentication:
|
||||
|
||||
| Environment | Redirect URI |
|
||||
| ----------- | -------------------------------------------------- |
|
||||
| Development | `http://localhost:3001/api/auth/google/callback` |
|
||||
| Production | `https://your-domain.com/api/auth/google/callback` |
|
||||
|
||||
### Step 3: Save Credentials
|
||||
|
||||
After clicking **Create**, you'll receive:
|
||||
|
||||
- **Client ID**
|
||||
- **Client Secret**
|
||||
|
||||
Store these securely as environment variables:
|
||||
|
||||
- `GOOGLE_CLIENT_ID`
|
||||
- `GOOGLE_CLIENT_SECRET`
|
||||
|
||||
---
|
||||
|
||||
## GitHub OAuth
|
||||
|
||||
### Step 1: Create OAuth App
|
||||
|
||||
1. Go to your [GitHub Developer Settings](https://github.com/settings/developers)
|
||||
2. Navigate to **OAuth Apps**
|
||||
3. Click **New OAuth App**
|
||||
|
||||
### Step 2: Fill in Application Details
|
||||
|
||||
| Field | Value |
|
||||
| -------------------------- | ---------------------------------------------------- |
|
||||
| Application name | Flyer Crawler (or your preferred name) |
|
||||
| Homepage URL | `http://localhost:5173` (dev) or your production URL |
|
||||
| Authorization callback URL | `http://localhost:3001/api/auth/github/callback` |
|
||||
|
||||
### Step 3: Save GitHub Credentials
|
||||
|
||||
After clicking **Register application**, you'll receive:
|
||||
|
||||
- **Client ID**
|
||||
- **Client Secret**
|
||||
|
||||
Store these securely as environment variables:
|
||||
|
||||
- `GITHUB_CLIENT_ID`
|
||||
- `GITHUB_CLIENT_SECRET`
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables Summary
|
||||
|
||||
| Variable | Description |
|
||||
| ---------------------- | ---------------------------------------- |
|
||||
| `GOOGLE_CLIENT_ID` | Google OAuth client ID |
|
||||
| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret |
|
||||
| `GITHUB_CLIENT_ID` | GitHub OAuth client ID |
|
||||
| `GITHUB_CLIENT_SECRET` | GitHub OAuth client secret |
|
||||
| `JWT_SECRET` | Secret for signing authentication tokens |
|
||||
|
||||
---
|
||||
|
||||
## Production Considerations
|
||||
|
||||
When deploying to production:
|
||||
|
||||
1. **Update redirect URIs** in both Google Cloud Console and GitHub OAuth settings to use your production domain
|
||||
2. **Use HTTPS** for all callback URLs in production
|
||||
3. **Store secrets securely** using your CI/CD platform's secrets management (e.g., Gitea repository secrets)
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "redirect_uri_mismatch" Error
|
||||
|
||||
The callback URL in your OAuth provider settings doesn't match what the application is sending. Verify:
|
||||
|
||||
- The URL is exactly correct (no trailing slashes, correct port)
|
||||
- You're using the right environment (dev vs production URLs)
|
||||
|
||||
### "invalid_client" Error
|
||||
|
||||
The Client ID or Client Secret is incorrect. Double-check your environment variables.
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Installation Guide](INSTALL.md) - Local development setup
|
||||
- [Deployment Guide](DEPLOYMENT.md) - Production deployment
|
||||
188
DATABASE.md
Normal file
188
DATABASE.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# Database Setup
|
||||
|
||||
Flyer Crawler uses PostgreSQL with several extensions for full-text search, geographic data, and UUID generation.
|
||||
|
||||
---
|
||||
|
||||
## Required Extensions
|
||||
|
||||
| Extension | Purpose |
|
||||
| ----------- | ------------------------------------------- |
|
||||
| `postgis` | Geographic/spatial data for store locations |
|
||||
| `pg_trgm` | Trigram matching for fuzzy text search |
|
||||
| `uuid-ossp` | UUID generation for primary keys |
|
||||
|
||||
---
|
||||
|
||||
## Production Database Setup
|
||||
|
||||
### Step 1: Install PostgreSQL
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install postgresql postgresql-contrib
|
||||
```
|
||||
|
||||
### Step 2: Create Database and User
|
||||
|
||||
Switch to the postgres system user:
|
||||
|
||||
```bash
|
||||
sudo -u postgres psql
|
||||
```
|
||||
|
||||
Run the following SQL commands (replace `'a_very_strong_password'` with a secure password):
|
||||
|
||||
```sql
|
||||
-- Create a new role for your application
|
||||
CREATE ROLE flyer_crawler_user WITH LOGIN PASSWORD 'a_very_strong_password';
|
||||
|
||||
-- Create the production database
|
||||
CREATE DATABASE "flyer-crawler-prod" WITH OWNER = flyer_crawler_user;
|
||||
|
||||
-- Connect to the new database
|
||||
\c "flyer-crawler-prod"
|
||||
|
||||
-- Install required extensions (must be done as superuser)
|
||||
CREATE EXTENSION IF NOT EXISTS postgis;
|
||||
CREATE EXTENSION IF NOT EXISTS pg_trgm;
|
||||
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
|
||||
|
||||
-- Exit
|
||||
\q
|
||||
```
|
||||
|
||||
### Step 3: Apply the Schema
|
||||
|
||||
Navigate to your project directory and run:
|
||||
|
||||
```bash
|
||||
psql -U flyer_crawler_user -d "flyer-crawler-prod" -f sql/master_schema_rollup.sql
|
||||
```
|
||||
|
||||
This creates all tables, functions, triggers, and seeds essential data (categories, master items).
|
||||
|
||||
### Step 4: Seed the Admin Account
|
||||
|
||||
Set the required environment variables and run the seed script:
|
||||
|
||||
```bash
|
||||
export DB_USER=flyer_crawler_user
|
||||
export DB_PASSWORD=your_password
|
||||
export DB_NAME="flyer-crawler-prod"
|
||||
export DB_HOST=localhost
|
||||
|
||||
npx tsx src/db/seed_admin_account.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test Database Setup
|
||||
|
||||
The test database is used by CI/CD pipelines and local test runs.
|
||||
|
||||
### Step 1: Create the Test Database
|
||||
|
||||
```bash
|
||||
sudo -u postgres psql
|
||||
```
|
||||
|
||||
```sql
|
||||
-- Create the test database
|
||||
CREATE DATABASE "flyer-crawler-test" WITH OWNER = flyer_crawler_user;
|
||||
|
||||
-- Connect to the test database
|
||||
\c "flyer-crawler-test"
|
||||
|
||||
-- Install required extensions
|
||||
CREATE EXTENSION IF NOT EXISTS postgis;
|
||||
CREATE EXTENSION IF NOT EXISTS pg_trgm;
|
||||
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
|
||||
|
||||
-- Grant schema ownership (required for test runner to reset schema)
|
||||
ALTER SCHEMA public OWNER TO flyer_crawler_user;
|
||||
|
||||
-- Exit
|
||||
\q
|
||||
```
|
||||
|
||||
### Step 2: Configure CI/CD Secrets
|
||||
|
||||
Ensure these secrets are set in your Gitea repository settings:
|
||||
|
||||
| Secret | Description |
|
||||
| ------------- | ------------------------------------------ |
|
||||
| `DB_HOST` | Database hostname (e.g., `localhost`) |
|
||||
| `DB_PORT` | Database port (e.g., `5432`) |
|
||||
| `DB_USER` | Database user (e.g., `flyer_crawler_user`) |
|
||||
| `DB_PASSWORD` | Database password |
|
||||
|
||||
---
|
||||
|
||||
## How the Test Pipeline Works
|
||||
|
||||
The CI pipeline uses a permanent test database that gets reset on each test run:
|
||||
|
||||
1. **Setup**: The vitest global setup script connects to `flyer-crawler-test`
|
||||
2. **Schema Reset**: Executes `sql/drop_tables.sql` (`DROP SCHEMA public CASCADE`)
|
||||
3. **Schema Application**: Runs `sql/master_schema_rollup.sql` to build a fresh schema
|
||||
4. **Test Execution**: Tests run against the clean database
|
||||
|
||||
This approach is faster than creating/destroying databases and doesn't require sudo access.
|
||||
|
||||
---
|
||||
|
||||
## Connecting to Production Database
|
||||
|
||||
```bash
|
||||
psql -h localhost -U flyer_crawler_user -d "flyer-crawler-prod" -W
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checking PostGIS Version
|
||||
|
||||
```sql
|
||||
SELECT version();
|
||||
SELECT PostGIS_Full_Version();
|
||||
```
|
||||
|
||||
Example output:
|
||||
|
||||
```
|
||||
PostgreSQL 14.19 (Ubuntu 14.19-0ubuntu0.22.04.1)
|
||||
POSTGIS="3.2.0 c3e3cc0" GEOS="3.10.2-CAPI-1.16.0" PROJ="8.2.1"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Schema Files
|
||||
|
||||
| File | Purpose |
|
||||
| ------------------------------ | --------------------------------------------------------- |
|
||||
| `sql/master_schema_rollup.sql` | Complete schema with all tables, functions, and seed data |
|
||||
| `sql/drop_tables.sql` | Drops entire schema (used by test runner) |
|
||||
| `sql/schema.sql.txt` | Legacy schema file (reference only) |
|
||||
|
||||
---
|
||||
|
||||
## Backup and Restore
|
||||
|
||||
### Create a Backup
|
||||
|
||||
```bash
|
||||
pg_dump -U flyer_crawler_user -d "flyer-crawler-prod" -F c -f backup.dump
|
||||
```
|
||||
|
||||
### Restore from Backup
|
||||
|
||||
```bash
|
||||
pg_restore -U flyer_crawler_user -d "flyer-crawler-prod" -c backup.dump
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Installation Guide](INSTALL.md) - Local development setup
|
||||
- [Deployment Guide](DEPLOYMENT.md) - Production deployment
|
||||
211
DEPLOYMENT.md
Normal file
211
DEPLOYMENT.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# Deployment Guide
|
||||
|
||||
This guide covers deploying Flyer Crawler to a production server.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Ubuntu server (22.04 LTS recommended)
|
||||
- PostgreSQL 14+ with PostGIS extension
|
||||
- Redis
|
||||
- Node.js 20.x
|
||||
- NGINX (reverse proxy)
|
||||
- PM2 (process manager)
|
||||
|
||||
---
|
||||
|
||||
## Server Setup
|
||||
|
||||
### Install Node.js
|
||||
|
||||
```bash
|
||||
curl -sL https://deb.nodesource.com/setup_20.x | sudo bash -
|
||||
sudo apt-get install -y nodejs
|
||||
```
|
||||
|
||||
### Install PM2
|
||||
|
||||
```bash
|
||||
sudo npm install -g pm2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Application Deployment
|
||||
|
||||
### Clone and Install
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd flyer-crawler.projectium.com
|
||||
npm install
|
||||
```
|
||||
|
||||
### Build for Production
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Start with PM2
|
||||
|
||||
```bash
|
||||
npm run start:prod
|
||||
```
|
||||
|
||||
This starts three PM2 processes:
|
||||
|
||||
- `flyer-crawler-api` - Main API server
|
||||
- `flyer-crawler-worker` - Background job worker
|
||||
- `flyer-crawler-analytics-worker` - Analytics processing worker
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables (Gitea Secrets)
|
||||
|
||||
For deployments using Gitea CI/CD workflows, configure these as **repository secrets**:
|
||||
|
||||
| Secret | Description |
|
||||
| --------------------------- | ------------------------------------------- |
|
||||
| `DB_HOST` | PostgreSQL server hostname |
|
||||
| `DB_USER` | PostgreSQL username |
|
||||
| `DB_PASSWORD` | PostgreSQL password |
|
||||
| `DB_DATABASE_PROD` | Production database name |
|
||||
| `REDIS_PASSWORD_PROD` | Production Redis password |
|
||||
| `REDIS_PASSWORD_TEST` | Test Redis password |
|
||||
| `JWT_SECRET` | Long, random string for signing auth tokens |
|
||||
| `VITE_GOOGLE_GENAI_API_KEY` | Google Gemini API key |
|
||||
| `GOOGLE_MAPS_API_KEY` | Google Maps Geocoding API key |
|
||||
|
||||
---
|
||||
|
||||
## NGINX Configuration
|
||||
|
||||
### Reverse Proxy Setup
|
||||
|
||||
Create a site configuration at `/etc/nginx/sites-available/flyer-crawler.projectium.com`:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name flyer-crawler.projectium.com;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:5173;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection 'upgrade';
|
||||
proxy_set_header Host $host;
|
||||
proxy_cache_bypass $http_upgrade;
|
||||
}
|
||||
|
||||
location /api {
|
||||
proxy_pass http://localhost:3001;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection 'upgrade';
|
||||
proxy_set_header Host $host;
|
||||
proxy_cache_bypass $http_upgrade;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Enable the site:
|
||||
|
||||
```bash
|
||||
sudo ln -s /etc/nginx/sites-available/flyer-crawler.projectium.com /etc/nginx/sites-enabled/
|
||||
sudo nginx -t
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
### MIME Types Fix for .mjs Files
|
||||
|
||||
If JavaScript modules (`.mjs` files) aren't loading correctly, add the proper MIME type.
|
||||
|
||||
**Option 1**: Edit the site configuration file directly:
|
||||
|
||||
```nginx
|
||||
# Add inside the server block
|
||||
types {
|
||||
application/javascript js mjs;
|
||||
}
|
||||
```
|
||||
|
||||
**Option 2**: Edit `/etc/nginx/mime.types` globally:
|
||||
|
||||
```
|
||||
# Change this line:
|
||||
application/javascript js;
|
||||
|
||||
# To:
|
||||
application/javascript js mjs;
|
||||
```
|
||||
|
||||
After changes:
|
||||
|
||||
```bash
|
||||
sudo nginx -t
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PM2 Log Management
|
||||
|
||||
Install and configure pm2-logrotate to manage log files:
|
||||
|
||||
```bash
|
||||
pm2 install pm2-logrotate
|
||||
pm2 set pm2-logrotate:max_size 10M
|
||||
pm2 set pm2-logrotate:retain 14
|
||||
pm2 set pm2-logrotate:compress false
|
||||
pm2 set pm2-logrotate:dateFormat YYYY-MM-DD_HH-mm-ss
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
The application respects the Gemini AI service's rate limits. You can adjust the `GEMINI_RPM` (requests per minute) environment variable in production as needed without changing the code.
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Pipeline
|
||||
|
||||
The project includes Gitea workflows at `.gitea/workflows/deploy.yml` that:
|
||||
|
||||
1. Run tests against a test database
|
||||
2. Build the application
|
||||
3. Deploy to production on successful builds
|
||||
|
||||
The workflow automatically:
|
||||
|
||||
- Sets up the test database schema before tests
|
||||
- Tears down test data after tests complete
|
||||
- Deploys to the production server
|
||||
|
||||
---
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Check PM2 Status
|
||||
|
||||
```bash
|
||||
pm2 status
|
||||
pm2 logs
|
||||
pm2 logs flyer-crawler-api --lines 100
|
||||
```
|
||||
|
||||
### Restart Services
|
||||
|
||||
```bash
|
||||
pm2 restart all
|
||||
pm2 restart flyer-crawler-api
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Database Setup](DATABASE.md) - PostgreSQL and PostGIS configuration
|
||||
- [Authentication Setup](AUTHENTICATION.md) - OAuth provider configuration
|
||||
- [Installation Guide](INSTALL.md) - Local development setup
|
||||
167
INSTALL.md
Normal file
167
INSTALL.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# Installation Guide
|
||||
|
||||
This guide covers setting up a local development environment for Flyer Crawler.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 20.x or later
|
||||
- Access to a PostgreSQL database (local or remote)
|
||||
- Redis instance (for session management)
|
||||
- Google Gemini API key
|
||||
- Google Maps API key (for geocoding)
|
||||
|
||||
## Quick Start
|
||||
|
||||
If you already have PostgreSQL and Redis configured:
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Run in development mode
|
||||
npm run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Development Environment with Podman (Recommended for Windows)
|
||||
|
||||
This approach uses Podman with an Ubuntu container for a consistent development environment.
|
||||
|
||||
### Step 1: Install Prerequisites on Windows
|
||||
|
||||
1. **Install WSL 2**: Podman on Windows relies on the Windows Subsystem for Linux.
|
||||
|
||||
```powershell
|
||||
wsl --install
|
||||
```
|
||||
|
||||
Run this in an administrator PowerShell.
|
||||
|
||||
2. **Install Podman Desktop**: Download and install [Podman Desktop for Windows](https://podman-desktop.io/).
|
||||
|
||||
### Step 2: Set Up Podman
|
||||
|
||||
1. **Initialize Podman**: Launch Podman Desktop. It will automatically set up its WSL 2 machine.
|
||||
2. **Start Podman**: Ensure the Podman machine is running from the Podman Desktop interface.
|
||||
|
||||
### Step 3: Set Up the Ubuntu Container
|
||||
|
||||
1. **Pull Ubuntu Image**:
|
||||
|
||||
```bash
|
||||
podman pull ubuntu:latest
|
||||
```
|
||||
|
||||
2. **Create a Podman Volume** (persists node_modules between container restarts):
|
||||
|
||||
```bash
|
||||
podman volume create node_modules_cache
|
||||
```
|
||||
|
||||
3. **Run the Ubuntu Container**:
|
||||
|
||||
Open a terminal in your project's root directory and run:
|
||||
|
||||
```bash
|
||||
podman run -it -p 3001:3001 -p 5173:5173 --name flyer-dev \
|
||||
-v "$(pwd):/app" \
|
||||
-v "node_modules_cache:/app/node_modules" \
|
||||
ubuntu:latest
|
||||
```
|
||||
|
||||
| Flag | Purpose |
|
||||
| ------------------------------------------- | ------------------------------------------------ |
|
||||
| `-p 3001:3001` | Forwards the backend server port |
|
||||
| `-p 5173:5173` | Forwards the Vite frontend server port |
|
||||
| `--name flyer-dev` | Names the container for easy reference |
|
||||
| `-v "...:/app"` | Mounts your project directory into the container |
|
||||
| `-v "node_modules_cache:/app/node_modules"` | Mounts the named volume for node_modules |
|
||||
|
||||
### Step 4: Configure the Ubuntu Environment
|
||||
|
||||
You are now inside the Ubuntu container's shell.
|
||||
|
||||
1. **Update Package Lists**:
|
||||
|
||||
```bash
|
||||
apt-get update
|
||||
```
|
||||
|
||||
2. **Install Dependencies**:
|
||||
|
||||
```bash
|
||||
apt-get install -y curl git
|
||||
curl -sL https://deb.nodesource.com/setup_20.x | bash -
|
||||
apt-get install -y nodejs
|
||||
```
|
||||
|
||||
3. **Navigate to Project Directory**:
|
||||
|
||||
```bash
|
||||
cd /app
|
||||
```
|
||||
|
||||
4. **Install Project Dependencies**:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### Step 5: Run the Development Server
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Step 6: Access the Application
|
||||
|
||||
- **Frontend**: http://localhost:5173
|
||||
- **Backend API**: http://localhost:3001
|
||||
|
||||
### Managing the Container
|
||||
|
||||
| Action | Command |
|
||||
| --------------------- | -------------------------------- |
|
||||
| Stop the container | Press `Ctrl+C`, then type `exit` |
|
||||
| Restart the container | `podman start -a -i flyer-dev` |
|
||||
| Remove the container | `podman rm flyer-dev` |
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
This project is configured to run in a CI/CD environment and does not use `.env` files. All configuration must be provided as environment variables.
|
||||
|
||||
For local development, you can export these in your shell or use your IDE's environment configuration:
|
||||
|
||||
| Variable | Description |
|
||||
| --------------------------- | ------------------------------------- |
|
||||
| `DB_HOST` | PostgreSQL server hostname |
|
||||
| `DB_USER` | PostgreSQL username |
|
||||
| `DB_PASSWORD` | PostgreSQL password |
|
||||
| `DB_DATABASE_PROD` | Production database name |
|
||||
| `JWT_SECRET` | Secret string for signing auth tokens |
|
||||
| `VITE_GOOGLE_GENAI_API_KEY` | Google Gemini API key |
|
||||
| `GOOGLE_MAPS_API_KEY` | Google Maps Geocoding API key |
|
||||
| `REDIS_PASSWORD_PROD` | Production Redis password |
|
||||
| `REDIS_PASSWORD_TEST` | Test Redis password |
|
||||
|
||||
---
|
||||
|
||||
## Seeding Development Users
|
||||
|
||||
To create initial test accounts (`admin@example.com` and `user@example.com`):
|
||||
|
||||
```bash
|
||||
npm run seed
|
||||
```
|
||||
|
||||
After running, you may need to restart your IDE's TypeScript server to pick up any generated types.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Database Setup](DATABASE.md) - Set up PostgreSQL with required extensions
|
||||
- [Authentication Setup](AUTHENTICATION.md) - Configure OAuth providers
|
||||
- [Deployment Guide](DEPLOYMENT.md) - Deploy to production
|
||||
451
README.md
451
README.md
@@ -1,424 +1,91 @@
|
||||
# Flyer Crawler - Grocery AI Analyzer
|
||||
|
||||
Flyer Crawler is a web application that uses the Google Gemini AI to extract, analyze, and manage data from grocery store flyers. Users can upload flyer images or PDFs, and the application will automatically identify items, prices, and sale dates, storing the structured data in a PostgreSQL database for historical analysis, price tracking, and personalized deal alerts.
|
||||
Flyer Crawler is a web application that uses Google Gemini AI to extract, analyze, and manage data from grocery store flyers. Users can upload flyer images or PDFs, and the application automatically identifies items, prices, and sale dates, storing structured data in a PostgreSQL database for historical analysis, price tracking, and personalized deal alerts.
|
||||
|
||||
We are working on an app to help people save money, by finding good deals that are only advertized in store flyers/ads. So, the primary purpose of the site is to make uploading flyers as easy as possible and as accurate as possible, and to store peoples needs, so sales can be matched to needs.
|
||||
**Our mission**: Help people save money by finding good deals that are only advertised in store flyers. The app makes uploading flyers as easy and accurate as possible, and matches sales to users' needs.
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
- **AI-Powered Data Extraction**: Upload PNG, JPG, or PDF flyers to automatically extract store names, sale dates, and a detailed list of items with prices and quantities.
|
||||
- **Bulk Import**: Process multiple flyers at once with a summary report of successes, skips (duplicates), and errors.
|
||||
- **Database Integration**: All extracted data is saved to a PostgreSQL database, enabling long-term persistence and analysis.
|
||||
- **Personalized Watchlist**: Authenticated users can create a "watchlist" of specific grocery items they want to track.
|
||||
- **Active Deal Alerts**: The app highlights current sales on your watched items from all valid flyers in the database.
|
||||
- **Price History Charts**: Visualize the price trends of your watched items over time.
|
||||
- **Shopping List Management**: Users can create multiple shopping lists, add items from flyers or their watchlist, and track purchased items.
|
||||
- **User Authentication & Management**: Secure user sign-up, login, and profile management, including a secure account deletion process.
|
||||
- **Dynamic UI**: A responsive interface with dark mode and a choice between metric/imperial unit systems.
|
||||
- **AI-Powered Data Extraction**: Upload PNG, JPG, or PDF flyers to automatically extract store names, sale dates, and detailed item lists with prices and quantities
|
||||
- **Bulk Import**: Process multiple flyers at once with summary reports of successes, skips (duplicates), and errors
|
||||
- **Personalized Watchlist**: Create a watchlist of specific grocery items you want to track
|
||||
- **Active Deal Alerts**: See current sales on your watched items from all valid flyers
|
||||
- **Price History Charts**: Visualize price trends of watched items over time
|
||||
- **Shopping List Management**: Create multiple shopping lists, add items from flyers or your watchlist, and track purchased items
|
||||
- **User Authentication**: Secure sign-up, login, profile management, and account deletion
|
||||
- **Dynamic UI**: Responsive interface with dark mode and metric/imperial unit systems
|
||||
|
||||
---
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Frontend**: React, TypeScript, Tailwind CSS
|
||||
- **AI**: Google Gemini API (`@google/genai`)
|
||||
- **Backend**: Node.js with Express
|
||||
- **Database**: PostgreSQL
|
||||
- **Authentication**: Passport.js
|
||||
- **UI Components**: Recharts for charts
|
||||
| Layer | Technology |
|
||||
| -------------- | ----------------------------------- |
|
||||
| Frontend | React, TypeScript, Tailwind CSS |
|
||||
| AI | Google Gemini API (`@google/genai`) |
|
||||
| Backend | Node.js, Express |
|
||||
| Database | PostgreSQL with PostGIS |
|
||||
| Authentication | Passport.js (Google, GitHub OAuth) |
|
||||
| Charts | Recharts |
|
||||
|
||||
---
|
||||
|
||||
## Required Secrets & Configuration
|
||||
|
||||
This project is configured to run in a CI/CD environment and does not use `.env` files. All configuration and secrets must be provided as environment variables. For deployments using the included Gitea workflows, these must be configured as **repository secrets** in your Gitea instance.
|
||||
|
||||
- **`DB_HOST`, `DB_USER`, `DB_PASSWORD`**: Credentials for your PostgreSQL server. The port is assumed to be `5432`.
|
||||
- **`DB_DATABASE_PROD`**: The name of your production database.
|
||||
- **`REDIS_PASSWORD_PROD`**: The password for your production Redis instance.
|
||||
- **`REDIS_PASSWORD_TEST`**: The password for your test Redis instance.
|
||||
- **`JWT_SECRET`**: A long, random, and secret string for signing authentication tokens.
|
||||
- **`VITE_GOOGLE_GENAI_API_KEY`**: Your Google Gemini API key.
|
||||
- **`GOOGLE_MAPS_API_KEY`**: Your Google Maps Geocoding API key.
|
||||
|
||||
## Setup and Installation
|
||||
|
||||
### Step 1: Set Up PostgreSQL Database
|
||||
|
||||
1. **Set up a PostgreSQL database instance.**
|
||||
2. **Run the Database Schema**:
|
||||
- Connect to your database using a tool like `psql` or DBeaver.
|
||||
- Open `sql/schema.sql.txt`, copy its entire contents, and execute it against your database.
|
||||
- This will create all necessary tables, functions, and relationships.
|
||||
|
||||
### Step 2: Install Dependencies and Run the Application
|
||||
|
||||
1. **Install Dependencies**:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
2. **Run the Application**:
|
||||
|
||||
```bash
|
||||
npm run start:prod
|
||||
```
|
||||
|
||||
### Step 3: Seed Development Users (Optional)
|
||||
|
||||
To create the initial `admin@example.com` and `user@example.com` accounts, you can run the seed script:
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
npm run seed
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Run in development mode
|
||||
npm run dev
|
||||
```
|
||||
|
||||
After running, you may need to restart your IDE's TypeScript server to pick up the changes.
|
||||
|
||||
## NGINX mime types issue
|
||||
|
||||
sudo nano /etc/nginx/mime.types
|
||||
|
||||
change
|
||||
|
||||
application/javascript js;
|
||||
|
||||
TO
|
||||
|
||||
application/javascript js mjs;
|
||||
|
||||
RESTART NGINX
|
||||
|
||||
sudo nginx -t
|
||||
sudo systemctl reload nginx
|
||||
|
||||
actually the proper change was to do this in the /etc/nginx/sites-available/flyer-crawler.projectium.com file
|
||||
|
||||
## for OAuth
|
||||
|
||||
1. Get Google OAuth Credentials
|
||||
This is a crucial step that you must do outside the codebase:
|
||||
|
||||
Go to the Google Cloud Console.
|
||||
|
||||
Create a new project (or select an existing one).
|
||||
|
||||
In the navigation menu, go to APIs & Services > Credentials.
|
||||
|
||||
Click Create Credentials > OAuth client ID.
|
||||
|
||||
Select Web application as the application type.
|
||||
|
||||
Under Authorized redirect URIs, click ADD URI and enter the URL where Google will redirect users back to your server. For local development, this will be: http://localhost:3001/api/auth/google/callback.
|
||||
|
||||
Click Create. You will be given a Client ID and a Client Secret.
|
||||
|
||||
2. Get GitHub OAuth Credentials
|
||||
You'll need to obtain a Client ID and Client Secret from GitHub:
|
||||
|
||||
Go to your GitHub profile settings.
|
||||
|
||||
Navigate to Developer settings > OAuth Apps.
|
||||
|
||||
Click New OAuth App.
|
||||
|
||||
Fill in the required fields:
|
||||
|
||||
Application name: A descriptive name for your app (e.g., "Flyer Crawler").
|
||||
Homepage URL: The base URL of your application (e.g., http://localhost:5173 for local development).
|
||||
Authorization callback URL: This is where GitHub will redirect users after they authorize your app. For local development, this will be: <http://localhost:3001/api/auth/github/callback>.
|
||||
Click Register application.
|
||||
|
||||
You will be given a Client ID and a Client Secret.
|
||||
|
||||
## connect to postgres on projectium.com
|
||||
|
||||
psql -h localhost -U flyer_crawler_user -d "flyer-crawler-prod" -W
|
||||
|
||||
## postgis
|
||||
|
||||
flyer-crawler-prod=> SELECT version();
|
||||
version
|
||||
See [INSTALL.md](INSTALL.md) for detailed setup instructions.
|
||||
|
||||
---
|
||||
|
||||
PostgreSQL 14.19 (Ubuntu 14.19-0ubuntu0.22.04.1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04.2) 11.4.0, 64-bit
|
||||
(1 row)
|
||||
## Documentation
|
||||
|
||||
flyer-crawler-prod=> SELECT PostGIS_Full_Version();
|
||||
postgis_full_version
|
||||
| Document | Description |
|
||||
| -------------------------------------- | ---------------------------------------- |
|
||||
| [INSTALL.md](INSTALL.md) | Local development setup with Podman |
|
||||
| [DATABASE.md](DATABASE.md) | PostgreSQL setup, schema, and extensions |
|
||||
| [AUTHENTICATION.md](AUTHENTICATION.md) | OAuth configuration (Google, GitHub) |
|
||||
| [DEPLOYMENT.md](DEPLOYMENT.md) | Production server setup, NGINX, PM2 |
|
||||
|
||||
---
|
||||
|
||||
POSTGIS="3.2.0 c3e3cc0" [EXTENSION] PGSQL="140" GEOS="3.10.2-CAPI-1.16.0" PROJ="8.2.1" LIBXML="2.9.12" LIBJSON="0.15" LIBPROTOBUF="1.3.3" WAGYU="0.5.0 (Internal)"
|
||||
(1 row)
|
||||
## Environment Variables
|
||||
|
||||
## production postgres setup
|
||||
This project uses environment variables for configuration (no `.env` files). Key variables:
|
||||
|
||||
Part 1: Production Database Setup
|
||||
This database will be the live, persistent storage for your application.
|
||||
| Variable | Description |
|
||||
| ----------------------------------- | -------------------------------- |
|
||||
| `DB_HOST`, `DB_USER`, `DB_PASSWORD` | PostgreSQL credentials |
|
||||
| `DB_DATABASE_PROD` | Production database name |
|
||||
| `JWT_SECRET` | Authentication token signing key |
|
||||
| `VITE_GOOGLE_GENAI_API_KEY` | Google Gemini API key |
|
||||
| `GOOGLE_MAPS_API_KEY` | Google Maps Geocoding API key |
|
||||
| `REDIS_PASSWORD_PROD` | Redis password |
|
||||
|
||||
Step 1: Install PostgreSQL (if not already installed)
|
||||
First, ensure PostgreSQL is installed on your server.
|
||||
See [INSTALL.md](INSTALL.md) for the complete list.
|
||||
|
||||
bash
|
||||
sudo apt update
|
||||
sudo apt install postgresql postgresql-contrib
|
||||
Step 2: Create the Production Database and User
|
||||
It's best practice to create a dedicated, non-superuser role for your application to connect with.
|
||||
---
|
||||
|
||||
Switch to the postgres system user to get superuser access to the database.
|
||||
## Scripts
|
||||
|
||||
bash
|
||||
sudo -u postgres psql
|
||||
Inside the psql shell, run the following SQL commands. Remember to replace 'a_very_strong_password' with a secure password that you will manage with a secrets tool or in your .env file.
|
||||
| Command | Description |
|
||||
| -------------------- | -------------------------------- |
|
||||
| `npm run dev` | Start development server |
|
||||
| `npm run build` | Build for production |
|
||||
| `npm run start:prod` | Start production server with PM2 |
|
||||
| `npm run test` | Run test suite |
|
||||
| `npm run seed` | Seed development user accounts |
|
||||
|
||||
sql
|
||||
-- Create a new role (user) for your application
|
||||
CREATE ROLE flyer_crawler_user WITH LOGIN PASSWORD 'a_very_strong_password';
|
||||
---
|
||||
|
||||
-- Create the production database and assign ownership to the new user
|
||||
CREATE DATABASE "flyer-crawler-prod" WITH OWNER = flyer_crawler_user;
|
||||
## License
|
||||
|
||||
-- Connect to the new database to install extensions within it.
|
||||
\c "flyer-crawler-prod"
|
||||
|
||||
-- Install the required extensions as a superuser. This only needs to be done once.
|
||||
CREATE EXTENSION IF NOT EXISTS postgis;
|
||||
CREATE EXTENSION IF NOT EXISTS pg_trgm;
|
||||
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
|
||||
|
||||
-- Exit the psql shell
|
||||
|
||||
Step 3: Apply the Master Schema
|
||||
Now, you'll populate your new database with all the tables, functions, and initial data. Your master_schema_rollup.sql file is perfect for this.
|
||||
|
||||
Navigate to your project's root directory on the server.
|
||||
|
||||
Run the following command to execute the master schema script against your new production database. You will be prompted for the password you created in the previous step.
|
||||
|
||||
bash
|
||||
psql -U flyer_crawler_user -d "flyer-crawler-prod" -f sql/master_schema_rollup.sql
|
||||
This single command creates all tables, extensions (pg_trgm, postgis), functions, and triggers, and seeds essential data like categories and master items.
|
||||
|
||||
Step 4: Seed the Admin Account (If Needed)
|
||||
Your application has a separate script to create the initial admin user. To run it, you must first set the required environment variables in your shell session.
|
||||
|
||||
bash
|
||||
|
||||
# Set variables for the current session
|
||||
|
||||
export DB_USER=flyer_crawler_user DB_PASSWORD=your_password DB_NAME="flyer-crawler-prod" ...
|
||||
|
||||
# Run the seeding script
|
||||
|
||||
npx tsx src/db/seed_admin_account.ts
|
||||
Your production database is now ready!
|
||||
|
||||
Part 2: Test Database Setup (for CI/CD)
|
||||
Your Gitea workflow (deploy.yml) already automates the creation and teardown of the test database during the pipeline run. The steps below are for understanding what the workflow does and for manual setup if you ever need to run tests outside the CI pipeline.
|
||||
|
||||
The process your CI pipeline follows is:
|
||||
|
||||
Setup (sql/test_setup.sql):
|
||||
|
||||
As the postgres superuser, it runs sql/test_setup.sql.
|
||||
This creates a temporary role named test_runner.
|
||||
It creates a separate database named "flyer-crawler-test" owned by test_runner.
|
||||
Schema Application (src/tests/setup/global-setup.ts):
|
||||
|
||||
The test runner (vitest) executes the global-setup.ts file.
|
||||
This script connects to the "flyer-crawler-test" database using the temporary credentials.
|
||||
It then runs the same sql/master_schema_rollup.sql file, ensuring your test database has the exact same structure as production.
|
||||
Test Execution:
|
||||
|
||||
Your tests run against this clean, isolated "flyer-crawler-test" database.
|
||||
Teardown (sql/test_teardown.sql):
|
||||
|
||||
After tests complete (whether they pass or fail), the if: always() step in your workflow ensures that sql/test_teardown.sql is executed.
|
||||
This script terminates any lingering connections to the test database, drops the "flyer-crawler-test" database completely, and drops the test_runner role.
|
||||
|
||||
Part 3: Test Database Setup (for CI/CD and Local Testing)
|
||||
Your Gitea workflow and local test runner rely on a permanent test database. This database needs to be created once on your server. The test runner will automatically reset the schema inside it before every test run.
|
||||
|
||||
Step 1: Create the Test Database
|
||||
On your server, switch to the postgres system user to get superuser access.
|
||||
|
||||
bash
|
||||
sudo -u postgres psql
|
||||
Inside the psql shell, create a new database. We will assign ownership to the same flyer_crawler_user that your application uses. This user needs to be the owner to have permission to drop and recreate the schema during testing.
|
||||
|
||||
sql
|
||||
-- Create the test database and assign ownership to your existing application user
|
||||
CREATE DATABASE "flyer-crawler-test" WITH OWNER = flyer_crawler_user;
|
||||
|
||||
-- Connect to the newly created test database
|
||||
\c "flyer-crawler-test"
|
||||
|
||||
-- Install the required extensions as a superuser. This only needs to be done once.
|
||||
CREATE EXTENSION IF NOT EXISTS postgis;
|
||||
CREATE EXTENSION IF NOT EXISTS pg_trgm;
|
||||
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
|
||||
|
||||
-- Connect to the newly created test database
|
||||
\c "flyer-crawler-test"
|
||||
|
||||
-- Grant ownership of the public schema within this database to your application user.
|
||||
-- This is CRITICAL for allowing the test runner to drop and recreate the schema.
|
||||
ALTER SCHEMA public OWNER TO flyer_crawler_user;
|
||||
|
||||
-- Exit the psql shell
|
||||
\q
|
||||
|
||||
Step 2: Configure Gitea Secrets for Testing
|
||||
Your CI pipeline needs to know how to connect to this test database. Ensure the following secrets are set in your Gitea repository settings:
|
||||
|
||||
DB_HOST: The hostname of your database server (e.g., localhost).
|
||||
DB_PORT: The port for your database (e.g., 5432).
|
||||
DB_USER: The user for the database (e.g., flyer_crawler_user).
|
||||
DB_PASSWORD: The password for the database user.
|
||||
The workflow file (.gitea/workflows/deploy.yml) is configured to use these secrets and will automatically connect to the "flyer-crawler-test" database when it runs the npm test command.
|
||||
|
||||
How the Test Workflow Works
|
||||
The CI pipeline no longer uses sudo or creates/destroys the database on each run. Instead, the process is now:
|
||||
|
||||
Setup: The vitest global setup script (src/tests/setup/global-setup.ts) connects to the permanent "flyer-crawler-test" database.
|
||||
|
||||
Schema Reset: It executes sql/drop_tables.sql (which runs DROP SCHEMA public CASCADE) to completely wipe all tables, functions, and triggers.
|
||||
|
||||
Schema Application: It then immediately executes sql/master_schema_rollup.sql to build a fresh, clean schema and seed initial data.
|
||||
|
||||
Test Execution: Your tests run against this clean, isolated schema.
|
||||
|
||||
This approach is faster, more reliable, and removes the need for sudo access within the CI pipeline.
|
||||
|
||||
gitea-runner@projectium:~$ pm2 install pm2-logrotate
|
||||
[PM2][Module] Installing NPM pm2-logrotate module
|
||||
[PM2][Module] Calling [NPM] to install pm2-logrotate ...
|
||||
|
||||
added 161 packages in 5s
|
||||
|
||||
21 packages are looking for funding
|
||||
run `npm fund` for details
|
||||
npm notice
|
||||
npm notice New patch version of npm available! 11.6.3 -> 11.6.4
|
||||
npm notice Changelog: https://github.com/npm/cli/releases/tag/v11.6.4
|
||||
npm notice To update run: npm install -g npm@11.6.4
|
||||
npm notice
|
||||
[PM2][Module] Module downloaded
|
||||
[PM2][WARN] Applications pm2-logrotate not running, starting...
|
||||
[PM2] App [pm2-logrotate] launched (1 instances)
|
||||
Module: pm2-logrotate
|
||||
$ pm2 set pm2-logrotate:max_size 10M
|
||||
$ pm2 set pm2-logrotate:retain 30
|
||||
$ pm2 set pm2-logrotate:compress false
|
||||
$ pm2 set pm2-logrotate:dateFormat YYYY-MM-DD_HH-mm-ss
|
||||
$ pm2 set pm2-logrotate:workerInterval 30
|
||||
$ pm2 set pm2-logrotate:rotateInterval 0 0 \* \* _
|
||||
$ pm2 set pm2-logrotate:rotateModule true
|
||||
Modules configuration. Copy/Paste line to edit values.
|
||||
[PM2][Module] Module successfully installed and launched
|
||||
[PM2][Module] Checkout module options: `$ pm2 conf`
|
||||
┌────┬───────────────────────────────────┬─────────────┬─────────┬─────────┬──────────┬────────┬──────┬───────────┬──────────┬──────────┬──────────┬──────────┐
|
||||
│ id │ name │ namespace │ version │ mode │ pid │ uptime │ ↺ │ status │ cpu │ mem │ user │ watching │
|
||||
├────┼───────────────────────────────────┼─────────────┼─────────┼─────────┼──────────┼────────┼──────┼───────────┼──────────┼──────────┼──────────┼──────────┤
|
||||
│ 2 │ flyer-crawler-analytics-worker │ default │ 0.0.0 │ fork │ 3846981 │ 7m │ 5 │ online │ 0% │ 55.8mb │ git… │ disabled │
|
||||
│ 11 │ flyer-crawler-api │ default │ 0.0.0 │ fork │ 3846987 │ 7m │ 0 │ online │ 0% │ 59.0mb │ git… │ disabled │
|
||||
│ 12 │ flyer-crawler-worker │ default │ 0.0.0 │ fork │ 3846988 │ 7m │ 0 │ online │ 0% │ 54.2mb │ git… │ disabled │
|
||||
└────┴───────────────────────────────────┴─────────────┴─────────┴─────────┴──────────┴────────┴──────┴───────────┴──────────┴──────────┴──────────┴──────────┘
|
||||
Module
|
||||
┌────┬──────────────────────────────┬───────────────┬──────────┬──────────┬──────┬──────────┬──────────┬──────────┐
|
||||
│ id │ module │ version │ pid │ status │ ↺ │ cpu │ mem │ user │
|
||||
├────┼──────────────────────────────┼───────────────┼──────────┼──────────┼──────┼──────────┼──────────┼──────────┤
|
||||
│ 13 │ pm2-logrotate │ 3.0.0 │ 3848878 │ online │ 0 │ 0% │ 20.1mb │ git… │
|
||||
└────┴──────────────────────────────┴───────────────┴──────────┴──────────┴──────┴──────────┴──────────┴──────────┘
|
||||
gitea-runner@projectium:~$ pm2 set pm2-logrotate:max_size 10M
|
||||
[PM2] Module pm2-logrotate restarted
|
||||
[PM2] Setting changed
|
||||
Module: pm2-logrotate
|
||||
$ pm2 set pm2-logrotate:max_size 10M
|
||||
$ pm2 set pm2-logrotate:retain 30
|
||||
$ pm2 set pm2-logrotate:compress false
|
||||
$ pm2 set pm2-logrotate:dateFormat YYYY-MM-DD_HH-mm-ss
|
||||
$ pm2 set pm2-logrotate:workerInterval 30
|
||||
$ pm2 set pm2-logrotate:rotateInterval 0 0 _ \* _
|
||||
$ pm2 set pm2-logrotate:rotateModule true
|
||||
gitea-runner@projectium:~$ pm2 set pm2-logrotate:retain 14
|
||||
[PM2] Module pm2-logrotate restarted
|
||||
[PM2] Setting changed
|
||||
Module: pm2-logrotate
|
||||
$ pm2 set pm2-logrotate:max_size 10M
|
||||
$ pm2 set pm2-logrotate:retain 14
|
||||
$ pm2 set pm2-logrotate:compress false
|
||||
$ pm2 set pm2-logrotate:dateFormat YYYY-MM-DD_HH-mm-ss
|
||||
$ pm2 set pm2-logrotate:workerInterval 30
|
||||
$ pm2 set pm2-logrotate:rotateInterval 0 0 _ \* \*
|
||||
$ pm2 set pm2-logrotate:rotateModule true
|
||||
gitea-runner@projectium:~$
|
||||
|
||||
## dev server setup:
|
||||
|
||||
Here are the steps to set up the development environment on Windows using Podman with an Ubuntu container:
|
||||
|
||||
1. Install Prerequisites on Windows
|
||||
Install WSL 2: Podman on Windows relies on the Windows Subsystem for Linux. Install it by running wsl --install in an administrator PowerShell.
|
||||
Install Podman Desktop: Download and install Podman Desktop for Windows.
|
||||
|
||||
2. Set Up Podman
|
||||
Initialize Podman: Launch Podman Desktop. It will automatically set up its WSL 2 machine.
|
||||
Start Podman: Ensure the Podman machine is running from the Podman Desktop interface.
|
||||
|
||||
3. Set Up the Ubuntu Container
|
||||
|
||||
- Pull Ubuntu Image: Open a PowerShell or command prompt and pull the latest Ubuntu image:
|
||||
podman pull ubuntu:latest
|
||||
- Create a Podman Volume: Create a volume to persist node_modules and avoid installing them every time the container starts.
|
||||
podman volume create node_modules_cache
|
||||
- Run the Ubuntu Container: Start a new container with the project directory mounted and the necessary ports forwarded.
|
||||
- Open a terminal in your project's root directory on Windows.
|
||||
- Run the following command, replacing D:\gitea\flyer-crawler.projectium.com\flyer-crawler.projectium.com with the full path to your project:
|
||||
|
||||
podman run -it -p 3001:3001 -p 5173:5173 --name flyer-dev -v "D:\gitea\flyer-crawler.projectium.com\flyer-crawler.projectium.com:/app" -v "node_modules_cache:/app/node_modules" ubuntu:latest
|
||||
|
||||
-p 3001:3001: Forwards the backend server port.
|
||||
-p 5173:5173: Forwards the Vite frontend server port.
|
||||
--name flyer-dev: Names the container for easy reference.
|
||||
-v "...:/app": Mounts your project directory into the container at /app.
|
||||
-v "node_modules_cache:/app/node_modules": Mounts the named volume for node_modules.
|
||||
|
||||
4. Configure the Ubuntu Environment
|
||||
You are now inside the Ubuntu container's shell.
|
||||
|
||||
- Update Package Lists:
|
||||
apt-get update
|
||||
- Install Dependencies: Install curl, git, and nodejs (which includes npm).
|
||||
apt-get install -y curl git
|
||||
curl -sL https://deb.nodesource.com/setup_20.x | bash -
|
||||
apt-get install -y nodejs
|
||||
- Navigate to Project Directory:
|
||||
cd /app
|
||||
|
||||
- Install Project Dependencies:
|
||||
npm install
|
||||
|
||||
5. Run the Development Server
|
||||
- Start the Application:
|
||||
npm run dev
|
||||
|
||||
6. Accessing the Application
|
||||
|
||||
- Frontend: Open your browser and go to http://localhost:5173.
|
||||
- Backend: The frontend will make API calls to http://localhost:3001.
|
||||
|
||||
Managing the Environment
|
||||
|
||||
- Stopping the Container: Press Ctrl+C in the container terminal, then type exit.
|
||||
- Restarting the Container:
|
||||
podman start -a -i flyer-dev
|
||||
|
||||
## for me:
|
||||
|
||||
cd /mnt/d/gitea/flyer-crawler.projectium.com/flyer-crawler.projectium.com
|
||||
podman run -it -p 3001:3001 -p 5173:5173 --name flyer-dev -v "$(pwd):/app" -v "node_modules_cache:/app/node_modules" ubuntu:latest
|
||||
|
||||
rate limiting
|
||||
|
||||
respect the AI service's rate limits, making it more stable and robust. You can adjust the GEMINI_RPM environment variable in your production environment as needed without changing the code.
|
||||
[Add license information here]
|
||||
|
||||
291
docs/adr/0041-ai-gemini-integration-architecture.md
Normal file
291
docs/adr/0041-ai-gemini-integration-architecture.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# ADR-041: AI/Gemini Integration Architecture
|
||||
|
||||
**Date**: 2026-01-09
|
||||
|
||||
**Status**: Accepted
|
||||
|
||||
**Implemented**: 2026-01-09
|
||||
|
||||
## Context
|
||||
|
||||
The application relies heavily on Google Gemini AI for core functionality:
|
||||
|
||||
1. **Flyer Processing**: Extracting store names, dates, addresses, and individual sale items from uploaded flyer images.
|
||||
2. **Receipt Analysis**: Parsing purchased items and prices from receipt images.
|
||||
3. **Recipe Suggestions**: Generating recipe ideas based on available ingredients.
|
||||
4. **Text Extraction**: OCR-style extraction from cropped image regions.
|
||||
|
||||
These AI operations have unique challenges:
|
||||
|
||||
- **Rate Limits**: Google AI API enforces requests-per-minute (RPM) limits.
|
||||
- **Quota Buckets**: Different model families (stable, preview, experimental) have separate quotas.
|
||||
- **Model Availability**: Models may be unavailable due to regional restrictions, updates, or high load.
|
||||
- **Cost Variability**: Different models have different pricing (Flash-Lite vs Pro).
|
||||
- **Output Limits**: Some models have 8k token limits, others 65k.
|
||||
- **Testability**: Tests must not make real API calls.
|
||||
|
||||
## Decision
|
||||
|
||||
We will implement a centralized `AIService` class with:
|
||||
|
||||
1. **Dependency Injection**: AI client and filesystem are injectable for testability.
|
||||
2. **Model Fallback Chain**: Automatic failover through prioritized model lists.
|
||||
3. **Rate Limiting**: Per-instance rate limiter using `p-ratelimit`.
|
||||
4. **Tiered Model Selection**: Different model lists for different task types.
|
||||
5. **Environment-Aware Mocking**: Automatic mock client in test environments.
|
||||
|
||||
### Design Principles
|
||||
|
||||
- **Single Responsibility**: `AIService` handles all AI interactions.
|
||||
- **Fail-Safe Fallbacks**: If a model fails, try the next one in the chain.
|
||||
- **Cost Optimization**: Use cheaper "lite" models for simple text tasks.
|
||||
- **Structured Logging**: Log all AI interactions with timing and model info.
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### AIService Class Structure
|
||||
|
||||
Located in `src/services/aiService.server.ts`:
|
||||
|
||||
```typescript
|
||||
interface IAiClient {
|
||||
generateContent(request: {
|
||||
contents: Content[];
|
||||
tools?: Tool[];
|
||||
useLiteModels?: boolean;
|
||||
}): Promise<GenerateContentResponse>;
|
||||
}
|
||||
|
||||
interface IFileSystem {
|
||||
readFile(path: string): Promise<Buffer>;
|
||||
}
|
||||
|
||||
export class AIService {
|
||||
private aiClient: IAiClient;
|
||||
private fs: IFileSystem;
|
||||
private rateLimiter: <T>(fn: () => Promise<T>) => Promise<T>;
|
||||
private logger: Logger;
|
||||
|
||||
constructor(logger: Logger, aiClient?: IAiClient, fs?: IFileSystem) {
|
||||
// If aiClient provided: use it (unit test)
|
||||
// Else if test environment: use internal mock (integration test)
|
||||
// Else: create real GoogleGenAI client (production)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Tiered Model Lists
|
||||
|
||||
Models are organized by task complexity and quota bucket:
|
||||
|
||||
```typescript
|
||||
// For image processing (vision + long output)
|
||||
private readonly models = [
|
||||
// Tier A: Fast & Stable
|
||||
'gemini-2.5-flash', // Primary, 65k output
|
||||
'gemini-2.5-flash-lite', // Cost-saver, 65k output
|
||||
|
||||
// Tier B: Heavy Lifters
|
||||
'gemini-2.5-pro', // Complex layouts, 65k output
|
||||
|
||||
// Tier C: Preview Bucket (separate quota)
|
||||
'gemini-3-flash-preview',
|
||||
'gemini-3-pro-preview',
|
||||
|
||||
// Tier D: Experimental Bucket
|
||||
'gemini-exp-1206',
|
||||
|
||||
// Tier E: Last Resort
|
||||
'gemma-3-27b-it',
|
||||
'gemini-2.0-flash-exp', // WARNING: 8k limit
|
||||
];
|
||||
|
||||
// For simple text tasks (recipes, categorization)
|
||||
private readonly models_lite = [
|
||||
'gemini-2.5-flash-lite',
|
||||
'gemini-2.0-flash-lite-001',
|
||||
'gemini-2.0-flash-001',
|
||||
'gemma-3-12b-it',
|
||||
'gemma-3-4b-it',
|
||||
'gemini-2.0-flash-exp',
|
||||
];
|
||||
```
|
||||
|
||||
### Fallback with Retry Logic
|
||||
|
||||
```typescript
|
||||
private async _generateWithFallback(
|
||||
genAI: GoogleGenAI,
|
||||
request: { contents: Content[]; tools?: Tool[] },
|
||||
models: string[],
|
||||
): Promise<GenerateContentResponse> {
|
||||
let lastError: Error | null = null;
|
||||
|
||||
for (const modelName of models) {
|
||||
try {
|
||||
return await genAI.models.generateContent({ model: modelName, ...request });
|
||||
} catch (error: unknown) {
|
||||
const errorMsg = extractErrorMessage(error);
|
||||
const isRetriable = [
|
||||
'quota', '429', '503', 'resource_exhausted',
|
||||
'overloaded', 'unavailable', 'not found'
|
||||
].some(term => errorMsg.toLowerCase().includes(term));
|
||||
|
||||
if (isRetriable) {
|
||||
this.logger.warn(`Model '${modelName}' failed, trying next...`);
|
||||
lastError = new Error(errorMsg);
|
||||
continue;
|
||||
}
|
||||
throw error; // Non-retriable error
|
||||
}
|
||||
}
|
||||
throw lastError || new Error('All AI models failed.');
|
||||
}
|
||||
```
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
```typescript
|
||||
const requestsPerMinute = parseInt(process.env.GEMINI_RPM || '5', 10);
|
||||
this.rateLimiter = pRateLimit({
|
||||
interval: 60 * 1000,
|
||||
rate: requestsPerMinute,
|
||||
concurrency: requestsPerMinute,
|
||||
});
|
||||
|
||||
// Usage:
|
||||
const result = await this.rateLimiter(() =>
|
||||
this.aiClient.generateContent({ contents: [...] })
|
||||
);
|
||||
```
|
||||
|
||||
### Test Environment Detection
|
||||
|
||||
```typescript
|
||||
const isTestEnvironment = process.env.NODE_ENV === 'test' || !!process.env.VITEST_POOL_ID;
|
||||
|
||||
if (aiClient) {
|
||||
// Unit test: use provided mock
|
||||
this.aiClient = aiClient;
|
||||
} else if (isTestEnvironment) {
|
||||
// Integration test: use internal mock
|
||||
this.aiClient = {
|
||||
generateContent: async () => ({
|
||||
text: JSON.stringify(this.getMockFlyerData()),
|
||||
}),
|
||||
};
|
||||
} else {
|
||||
// Production: use real client
|
||||
const genAI = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
|
||||
this.aiClient = { generateContent: /* adapter */ };
|
||||
}
|
||||
```
|
||||
|
||||
### Prompt Engineering
|
||||
|
||||
Prompts are constructed with:
|
||||
|
||||
1. **Clear Task Definition**: What to extract and in what format.
|
||||
2. **Structured Output Requirements**: JSON schema with field descriptions.
|
||||
3. **Examples**: Concrete examples of expected output.
|
||||
4. **Context Hints**: User location for store address resolution.
|
||||
|
||||
```typescript
|
||||
private _buildFlyerExtractionPrompt(
|
||||
masterItems: MasterGroceryItem[],
|
||||
submitterIp?: string,
|
||||
userProfileAddress?: string,
|
||||
): string {
|
||||
// Location hint for address resolution
|
||||
let locationHint = '';
|
||||
if (userProfileAddress) {
|
||||
locationHint = `The user has profile address "${userProfileAddress}"...`;
|
||||
}
|
||||
|
||||
// Simplified master item list (reduce token usage)
|
||||
const simplifiedMasterList = masterItems.map(item => ({
|
||||
id: item.master_grocery_item_id,
|
||||
name: item.name,
|
||||
}));
|
||||
|
||||
return `
|
||||
# TASK
|
||||
Analyze the flyer image(s) and extract...
|
||||
|
||||
# RULES
|
||||
1. Extract store_name, valid_from, valid_to, store_address
|
||||
2. Extract items array with item, price_display, price_in_cents...
|
||||
|
||||
# EXAMPLES
|
||||
- { "item": "Red Grapes", "price_display": "$1.99 /lb", ... }
|
||||
|
||||
# MASTER LIST
|
||||
${JSON.stringify(simplifiedMasterList)}
|
||||
`;
|
||||
}
|
||||
```
|
||||
|
||||
### Response Parsing
|
||||
|
||||
AI responses may contain markdown, trailing text, or formatting issues:
|
||||
|
||||
````typescript
|
||||
private _parseJsonFromAiResponse<T>(responseText: string | undefined, logger: Logger): T | null {
|
||||
if (!responseText) return null;
|
||||
|
||||
// Try to extract from markdown code block
|
||||
const markdownMatch = responseText.match(/```(json)?\s*([\s\S]*?)\s*```/);
|
||||
let jsonString = markdownMatch?.[2]?.trim() || responseText;
|
||||
|
||||
// Find JSON boundaries
|
||||
const startIndex = Math.min(
|
||||
jsonString.indexOf('{') >= 0 ? jsonString.indexOf('{') : Infinity,
|
||||
jsonString.indexOf('[') >= 0 ? jsonString.indexOf('[') : Infinity
|
||||
);
|
||||
const endIndex = Math.max(jsonString.lastIndexOf('}'), jsonString.lastIndexOf(']'));
|
||||
|
||||
if (startIndex === Infinity || endIndex === -1) return null;
|
||||
|
||||
try {
|
||||
return JSON.parse(jsonString.substring(startIndex, endIndex + 1));
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- **Resilience**: Automatic failover when models are unavailable or rate-limited.
|
||||
- **Cost Control**: Uses cheaper models for simple tasks.
|
||||
- **Testability**: Full mock support for unit and integration tests.
|
||||
- **Observability**: Detailed logging of all AI operations with timing.
|
||||
- **Maintainability**: Centralized AI logic in one service.
|
||||
|
||||
### Negative
|
||||
|
||||
- **Model List Maintenance**: Must update model lists when new models release.
|
||||
- **Complexity**: Fallback logic adds complexity.
|
||||
- **Delayed Failures**: May take longer to fail if all models are down.
|
||||
|
||||
### Mitigation
|
||||
|
||||
- Monitor model deprecation announcements from Google.
|
||||
- Add health checks that validate AI connectivity on startup.
|
||||
- Consider caching successful model selections per task type.
|
||||
|
||||
## Key Files
|
||||
|
||||
- `src/services/aiService.server.ts` - Main AIService class
|
||||
- `src/services/aiService.server.test.ts` - Unit tests with mocked AI client
|
||||
- `src/services/aiApiClient.ts` - Low-level API client wrapper
|
||||
- `src/services/aiAnalysisService.ts` - Higher-level analysis orchestration
|
||||
- `src/types/ai.ts` - Zod schemas for AI response validation
|
||||
|
||||
## Related ADRs
|
||||
|
||||
- [ADR-027](./0027-standardized-naming-convention-for-ai-and-database-types.md) - Naming Conventions for AI Types
|
||||
- [ADR-039](./0039-dependency-injection-pattern.md) - Dependency Injection Pattern
|
||||
- [ADR-001](./0001-standardized-error-handling.md) - Error Handling
|
||||
329
docs/adr/0042-email-and-notification-architecture.md
Normal file
329
docs/adr/0042-email-and-notification-architecture.md
Normal file
@@ -0,0 +1,329 @@
|
||||
# ADR-042: Email and Notification Architecture
|
||||
|
||||
**Date**: 2026-01-09
|
||||
|
||||
**Status**: Accepted
|
||||
|
||||
**Implemented**: 2026-01-09
|
||||
|
||||
## Context
|
||||
|
||||
The application sends emails for multiple purposes:
|
||||
|
||||
1. **Transactional Emails**: Password reset, welcome emails, account verification.
|
||||
2. **Deal Notifications**: Alerting users when watched items go on sale.
|
||||
3. **Bulk Communications**: System announcements, marketing (future).
|
||||
|
||||
Email delivery has unique challenges:
|
||||
|
||||
- **Reliability**: Emails must be delivered even if the main request fails.
|
||||
- **Rate Limits**: SMTP servers enforce sending limits.
|
||||
- **Retry Logic**: Failed emails should be retried with backoff.
|
||||
- **Templating**: Emails need consistent branding and formatting.
|
||||
- **Testing**: Tests should not send real emails.
|
||||
|
||||
## Decision
|
||||
|
||||
We will implement a queue-based email system using:
|
||||
|
||||
1. **Nodemailer**: For SMTP transport and email composition.
|
||||
2. **BullMQ**: For job queuing, retry logic, and rate limiting.
|
||||
3. **Dedicated Worker**: Background process for email delivery.
|
||||
4. **Structured Logging**: Job-scoped logging for debugging.
|
||||
|
||||
### Design Principles
|
||||
|
||||
- **Asynchronous Delivery**: Queue emails immediately, deliver asynchronously.
|
||||
- **Idempotent Jobs**: Jobs can be retried safely.
|
||||
- **Separation of Concerns**: Email composition separate from delivery.
|
||||
- **Environment-Aware**: Disable real sending in test environments.
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Email Service Structure
|
||||
|
||||
Located in `src/services/emailService.server.ts`:
|
||||
|
||||
```typescript
|
||||
import nodemailer from 'nodemailer';
|
||||
import type { Job } from 'bullmq';
|
||||
import type { Logger } from 'pino';
|
||||
|
||||
// SMTP transporter configured from environment
|
||||
const transporter = nodemailer.createTransport({
|
||||
host: process.env.SMTP_HOST,
|
||||
port: parseInt(process.env.SMTP_PORT || '587', 10),
|
||||
secure: process.env.SMTP_SECURE === 'true',
|
||||
auth: {
|
||||
user: process.env.SMTP_USER,
|
||||
pass: process.env.SMTP_PASS,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Email Job Data Structure
|
||||
|
||||
```typescript
|
||||
// src/types/job-data.ts
|
||||
export interface EmailJobData {
|
||||
to: string;
|
||||
subject: string;
|
||||
text: string;
|
||||
html: string;
|
||||
}
|
||||
```
|
||||
|
||||
### Core Send Function
|
||||
|
||||
```typescript
|
||||
export const sendEmail = async (options: EmailJobData, logger: Logger) => {
|
||||
const mailOptions = {
|
||||
from: `"Flyer Crawler" <${process.env.SMTP_FROM_EMAIL}>`,
|
||||
to: options.to,
|
||||
subject: options.subject,
|
||||
text: options.text,
|
||||
html: options.html,
|
||||
};
|
||||
|
||||
const info = await transporter.sendMail(mailOptions);
|
||||
logger.info(
|
||||
{ to: options.to, subject: options.subject, messageId: info.messageId },
|
||||
'Email sent successfully.',
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
### Job Processor
|
||||
|
||||
```typescript
|
||||
export const processEmailJob = async (job: Job<EmailJobData>) => {
|
||||
// Create child logger with job context
|
||||
const jobLogger = globalLogger.child({
|
||||
jobId: job.id,
|
||||
jobName: job.name,
|
||||
recipient: job.data.to,
|
||||
});
|
||||
|
||||
jobLogger.info('Picked up email job.');
|
||||
|
||||
try {
|
||||
await sendEmail(job.data, jobLogger);
|
||||
} catch (error) {
|
||||
const wrappedError = error instanceof Error ? error : new Error(String(error));
|
||||
jobLogger.error({ err: wrappedError, attemptsMade: job.attemptsMade }, 'Email job failed.');
|
||||
throw wrappedError; // BullMQ will retry
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### Specialized Email Functions
|
||||
|
||||
#### Password Reset
|
||||
|
||||
```typescript
|
||||
export const sendPasswordResetEmail = async (to: string, token: string, logger: Logger) => {
|
||||
const resetUrl = `${process.env.FRONTEND_URL}/reset-password?token=${token}`;
|
||||
|
||||
const html = `
|
||||
<div style="font-family: sans-serif; padding: 20px;">
|
||||
<h2>Password Reset Request</h2>
|
||||
<p>Click the link below to set a new password. This link expires in 1 hour.</p>
|
||||
<a href="${resetUrl}" style="background-color: #007bff; color: white; padding: 14px 25px; ...">
|
||||
Reset Your Password
|
||||
</a>
|
||||
<p>If you did not request this, please ignore this email.</p>
|
||||
</div>
|
||||
`;
|
||||
|
||||
await sendEmail({ to, subject: 'Your Password Reset Request', text: '...', html }, logger);
|
||||
};
|
||||
```
|
||||
|
||||
#### Welcome Email
|
||||
|
||||
```typescript
|
||||
export const sendWelcomeEmail = async (to: string, name: string | null, logger: Logger) => {
|
||||
const recipientName = name || 'there';
|
||||
const html = `
|
||||
<div style="font-family: sans-serif; padding: 20px;">
|
||||
<h2>Welcome!</h2>
|
||||
<p>Hello ${recipientName},</p>
|
||||
<p>Thank you for joining Flyer Crawler.</p>
|
||||
<p>Start by uploading your first flyer to see how much you can save!</p>
|
||||
</div>
|
||||
`;
|
||||
|
||||
await sendEmail({ to, subject: 'Welcome to Flyer Crawler!', text: '...', html }, logger);
|
||||
};
|
||||
```
|
||||
|
||||
#### Deal Notifications
|
||||
|
||||
```typescript
|
||||
export const sendDealNotificationEmail = async (
|
||||
to: string,
|
||||
name: string | null,
|
||||
deals: WatchedItemDeal[],
|
||||
logger: Logger,
|
||||
) => {
|
||||
const dealsListHtml = deals
|
||||
.map(
|
||||
(deal) => `
|
||||
<li>
|
||||
<strong>${deal.item_name}</strong> is on sale for
|
||||
<strong>$${(deal.best_price_in_cents / 100).toFixed(2)}</strong>
|
||||
at ${deal.store_name}!
|
||||
</li>
|
||||
`,
|
||||
)
|
||||
.join('');
|
||||
|
||||
const html = `
|
||||
<h1>Hi ${name || 'there'},</h1>
|
||||
<p>We found great deals on items you're watching:</p>
|
||||
<ul>${dealsListHtml}</ul>
|
||||
<p>Check them out on the deals page!</p>
|
||||
`;
|
||||
|
||||
await sendEmail({ to, subject: 'New Deals Found!', text: '...', html }, logger);
|
||||
};
|
||||
```
|
||||
|
||||
### Queue Configuration
|
||||
|
||||
Located in `src/services/queueService.server.ts`:
|
||||
|
||||
```typescript
|
||||
import { Queue, Worker, Job } from 'bullmq';
|
||||
import { processEmailJob } from './emailService.server';
|
||||
|
||||
export const emailQueue = new Queue<EmailJobData>('email', {
|
||||
connection: redisConnection,
|
||||
defaultJobOptions: {
|
||||
attempts: 3,
|
||||
backoff: {
|
||||
type: 'exponential',
|
||||
delay: 1000,
|
||||
},
|
||||
removeOnComplete: 100,
|
||||
removeOnFail: 500,
|
||||
},
|
||||
});
|
||||
|
||||
// Worker to process email jobs
|
||||
const emailWorker = new Worker('email', processEmailJob, {
|
||||
connection: redisConnection,
|
||||
concurrency: 5,
|
||||
});
|
||||
```
|
||||
|
||||
### Enqueueing Emails
|
||||
|
||||
```typescript
|
||||
// From backgroundJobService.ts
|
||||
await emailQueue.add('deal-notification', {
|
||||
to: user.email,
|
||||
subject: 'New Deals Found!',
|
||||
text: textContent,
|
||||
html: htmlContent,
|
||||
});
|
||||
```
|
||||
|
||||
### Background Job Integration
|
||||
|
||||
Located in `src/services/backgroundJobService.ts`:
|
||||
|
||||
```typescript
|
||||
export class BackgroundJobService {
|
||||
constructor(
|
||||
private personalizationRepo: PersonalizationRepository,
|
||||
private notificationRepo: NotificationRepository,
|
||||
private emailQueue: Queue<EmailJobData>,
|
||||
private logger: Logger,
|
||||
) {}
|
||||
|
||||
async runDailyDealCheck(): Promise<void> {
|
||||
this.logger.info('Starting daily deal check...');
|
||||
|
||||
const deals = await this.personalizationRepo.getBestSalePricesForAllUsers(this.logger);
|
||||
|
||||
for (const userDeals of deals) {
|
||||
await this.emailQueue.add('deal-notification', {
|
||||
to: userDeals.email,
|
||||
subject: 'New Deals Found!',
|
||||
text: '...',
|
||||
html: '...',
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```bash
|
||||
# SMTP Configuration
|
||||
SMTP_HOST=smtp.example.com
|
||||
SMTP_PORT=587
|
||||
SMTP_SECURE=false
|
||||
SMTP_USER=user@example.com
|
||||
SMTP_PASS=secret
|
||||
SMTP_FROM_EMAIL=noreply@flyer-crawler.com
|
||||
|
||||
# Frontend URL for email links
|
||||
FRONTEND_URL=https://flyer-crawler.com
|
||||
```
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- **Reliability**: Failed emails are automatically retried with exponential backoff.
|
||||
- **Scalability**: Queue can handle burst traffic without overwhelming SMTP.
|
||||
- **Observability**: Job-scoped logging enables easy debugging.
|
||||
- **Separation**: Email composition is decoupled from delivery timing.
|
||||
- **Testability**: Can mock the queue or use Ethereal for testing.
|
||||
|
||||
### Negative
|
||||
|
||||
- **Complexity**: Adds queue infrastructure dependency (Redis).
|
||||
- **Delayed Delivery**: Emails are not instant (queued first).
|
||||
- **Monitoring Required**: Need to monitor queue depth and failure rates.
|
||||
|
||||
### Mitigation
|
||||
|
||||
- Use Bull Board UI for queue monitoring (already implemented).
|
||||
- Set up alerts for queue depth and failure rate thresholds.
|
||||
- Consider Ethereal or MailHog for development/testing.
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
```typescript
|
||||
// Unit test with mocked queue
|
||||
const mockEmailQueue = {
|
||||
add: vi.fn().mockResolvedValue({ id: 'job-1' }),
|
||||
};
|
||||
|
||||
const service = new BackgroundJobService(
|
||||
mockPersonalizationRepo,
|
||||
mockNotificationRepo,
|
||||
mockEmailQueue as any,
|
||||
mockLogger,
|
||||
);
|
||||
|
||||
await service.runDailyDealCheck();
|
||||
expect(mockEmailQueue.add).toHaveBeenCalledWith('deal-notification', expect.any(Object));
|
||||
```
|
||||
|
||||
## Key Files
|
||||
|
||||
- `src/services/emailService.server.ts` - Email composition and sending
|
||||
- `src/services/queueService.server.ts` - Queue configuration and workers
|
||||
- `src/services/backgroundJobService.ts` - Scheduled deal notifications
|
||||
- `src/types/job-data.ts` - Email job data types
|
||||
|
||||
## Related ADRs
|
||||
|
||||
- [ADR-006](./0006-background-job-processing-and-task-queues.md) - Background Job Processing
|
||||
- [ADR-004](./0004-standardized-application-wide-structured-logging.md) - Structured Logging
|
||||
- [ADR-039](./0039-dependency-injection-pattern.md) - Dependency Injection
|
||||
392
docs/adr/0043-express-middleware-pipeline.md
Normal file
392
docs/adr/0043-express-middleware-pipeline.md
Normal file
@@ -0,0 +1,392 @@
|
||||
# ADR-043: Express Middleware Pipeline Architecture
|
||||
|
||||
**Date**: 2026-01-09
|
||||
|
||||
**Status**: Accepted
|
||||
|
||||
**Implemented**: 2026-01-09
|
||||
|
||||
## Context
|
||||
|
||||
The Express application uses a layered middleware pipeline to handle cross-cutting concerns:
|
||||
|
||||
1. **Security**: Helmet headers, CORS, rate limiting.
|
||||
2. **Parsing**: JSON body, URL-encoded, cookies.
|
||||
3. **Authentication**: Session management, JWT verification.
|
||||
4. **Validation**: Request body/params validation.
|
||||
5. **File Handling**: Multipart form data, file uploads.
|
||||
6. **Error Handling**: Centralized error responses.
|
||||
|
||||
Middleware ordering is critical - incorrect ordering can cause security vulnerabilities or broken functionality. This ADR documents the canonical middleware order and patterns.
|
||||
|
||||
## Decision
|
||||
|
||||
We will establish a strict middleware ordering convention:
|
||||
|
||||
1. **Security First**: Security headers and protections apply to all requests.
|
||||
2. **Parsing Before Logic**: Body/cookie parsing before route handlers.
|
||||
3. **Auth Before Routes**: Authentication middleware before protected routes.
|
||||
4. **Validation At Route Level**: Per-route validation middleware.
|
||||
5. **Error Handler Last**: Centralized error handling catches all errors.
|
||||
|
||||
### Design Principles
|
||||
|
||||
- **Defense in Depth**: Multiple security layers.
|
||||
- **Fail-Fast**: Reject bad requests early in the pipeline.
|
||||
- **Explicit Ordering**: Document and enforce middleware order.
|
||||
- **Route-Level Flexibility**: Specific middleware per route as needed.
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Global Middleware Order
|
||||
|
||||
Located in `src/server.ts`:
|
||||
|
||||
```typescript
|
||||
import express from 'express';
|
||||
import helmet from 'helmet';
|
||||
import cors from 'cors';
|
||||
import cookieParser from 'cookie-parser';
|
||||
import { requestTimeoutMiddleware } from './middleware/timeout.middleware';
|
||||
import { rateLimiter } from './middleware/rateLimit.middleware';
|
||||
import { errorHandler } from './middleware/errorHandler.middleware';
|
||||
|
||||
const app = express();
|
||||
|
||||
// ============================================
|
||||
// LAYER 1: Security Headers & Protections
|
||||
// ============================================
|
||||
app.use(
|
||||
helmet({
|
||||
contentSecurityPolicy: {
|
||||
directives: {
|
||||
defaultSrc: ["'self'"],
|
||||
scriptSrc: ["'self'", "'unsafe-inline'"],
|
||||
styleSrc: ["'self'", "'unsafe-inline'"],
|
||||
imgSrc: ["'self'", 'data:', 'blob:'],
|
||||
},
|
||||
},
|
||||
}),
|
||||
);
|
||||
app.use(
|
||||
cors({
|
||||
origin: process.env.FRONTEND_URL,
|
||||
credentials: true,
|
||||
}),
|
||||
);
|
||||
|
||||
// ============================================
|
||||
// LAYER 2: Request Limits & Timeouts
|
||||
// ============================================
|
||||
app.use(requestTimeoutMiddleware(30000)); // 30s default
|
||||
app.use(rateLimiter); // Rate limiting per IP
|
||||
|
||||
// ============================================
|
||||
// LAYER 3: Body & Cookie Parsing
|
||||
// ============================================
|
||||
app.use(express.json({ limit: '10mb' }));
|
||||
app.use(express.urlencoded({ extended: true, limit: '10mb' }));
|
||||
app.use(cookieParser());
|
||||
|
||||
// ============================================
|
||||
// LAYER 4: Static Assets (before auth)
|
||||
// ============================================
|
||||
app.use('/flyer-images', express.static('flyer-images'));
|
||||
|
||||
// ============================================
|
||||
// LAYER 5: Authentication Setup
|
||||
// ============================================
|
||||
app.use(passport.initialize());
|
||||
app.use(passport.session());
|
||||
|
||||
// ============================================
|
||||
// LAYER 6: Routes (with per-route middleware)
|
||||
// ============================================
|
||||
app.use('/api/auth', authRoutes);
|
||||
app.use('/api/flyers', flyerRoutes);
|
||||
app.use('/api/admin', adminRoutes);
|
||||
// ... more routes
|
||||
|
||||
// ============================================
|
||||
// LAYER 7: Error Handling (must be last)
|
||||
// ============================================
|
||||
app.use(errorHandler);
|
||||
```
|
||||
|
||||
### Validation Middleware
|
||||
|
||||
Located in `src/middleware/validation.middleware.ts`:
|
||||
|
||||
```typescript
|
||||
import { z } from 'zod';
|
||||
import { Request, Response, NextFunction } from 'express';
|
||||
import { ValidationError } from '../services/db/errors.db';
|
||||
|
||||
export const validate = <T extends z.ZodType>(schema: T) => {
|
||||
return (req: Request, res: Response, next: NextFunction) => {
|
||||
const result = schema.safeParse({
|
||||
body: req.body,
|
||||
query: req.query,
|
||||
params: req.params,
|
||||
});
|
||||
|
||||
if (!result.success) {
|
||||
const errors = result.error.errors.map((err) => ({
|
||||
path: err.path.join('.'),
|
||||
message: err.message,
|
||||
}));
|
||||
return next(new ValidationError(errors));
|
||||
}
|
||||
|
||||
// Attach validated data to request
|
||||
req.validated = result.data;
|
||||
next();
|
||||
};
|
||||
};
|
||||
|
||||
// Usage in routes:
|
||||
router.post('/flyers', authenticate, validate(CreateFlyerSchema), flyerController.create);
|
||||
```
|
||||
|
||||
### File Upload Middleware
|
||||
|
||||
Located in `src/middleware/fileUpload.middleware.ts`:
|
||||
|
||||
```typescript
|
||||
import multer from 'multer';
|
||||
import path from 'path';
|
||||
import { v4 as uuidv4 } from 'uuid';
|
||||
|
||||
const storage = multer.diskStorage({
|
||||
destination: (req, file, cb) => {
|
||||
cb(null, 'flyer-images/');
|
||||
},
|
||||
filename: (req, file, cb) => {
|
||||
const ext = path.extname(file.originalname);
|
||||
cb(null, `${uuidv4()}${ext}`);
|
||||
},
|
||||
});
|
||||
|
||||
const fileFilter = (req: Request, file: Express.Multer.File, cb: multer.FileFilterCallback) => {
|
||||
const allowedTypes = ['image/jpeg', 'image/png', 'image/webp', 'application/pdf'];
|
||||
if (allowedTypes.includes(file.mimetype)) {
|
||||
cb(null, true);
|
||||
} else {
|
||||
cb(new Error('Invalid file type'));
|
||||
}
|
||||
};
|
||||
|
||||
export const uploadFlyer = multer({
|
||||
storage,
|
||||
fileFilter,
|
||||
limits: {
|
||||
fileSize: 10 * 1024 * 1024, // 10MB
|
||||
files: 10, // Max 10 files per request
|
||||
},
|
||||
});
|
||||
|
||||
// Usage:
|
||||
router.post('/flyers/upload', uploadFlyer.array('files', 10), flyerController.upload);
|
||||
```
|
||||
|
||||
### Authentication Middleware
|
||||
|
||||
Located in `src/middleware/auth.middleware.ts`:
|
||||
|
||||
```typescript
|
||||
import passport from 'passport';
|
||||
import { Request, Response, NextFunction } from 'express';
|
||||
|
||||
// Require authenticated user
|
||||
export const authenticate = (req: Request, res: Response, next: NextFunction) => {
|
||||
passport.authenticate('jwt', { session: false }, (err, user) => {
|
||||
if (err) return next(err);
|
||||
if (!user) {
|
||||
return res.status(401).json({ error: 'Unauthorized' });
|
||||
}
|
||||
req.user = user;
|
||||
next();
|
||||
})(req, res, next);
|
||||
};
|
||||
|
||||
// Require admin role
|
||||
export const requireAdmin = (req: Request, res: Response, next: NextFunction) => {
|
||||
if (!req.user?.role || req.user.role !== 'admin') {
|
||||
return res.status(403).json({ error: 'Forbidden' });
|
||||
}
|
||||
next();
|
||||
};
|
||||
|
||||
// Optional auth (attach user if present, continue if not)
|
||||
export const optionalAuth = (req: Request, res: Response, next: NextFunction) => {
|
||||
passport.authenticate('jwt', { session: false }, (err, user) => {
|
||||
if (user) req.user = user;
|
||||
next();
|
||||
})(req, res, next);
|
||||
};
|
||||
```
|
||||
|
||||
### Error Handler Middleware
|
||||
|
||||
Located in `src/middleware/errorHandler.middleware.ts`:
|
||||
|
||||
```typescript
|
||||
import { Request, Response, NextFunction } from 'express';
|
||||
import { v4 as uuidv4 } from 'uuid';
|
||||
import { logger } from '../services/logger.server';
|
||||
import { ValidationError, NotFoundError, UniqueConstraintError } from '../services/db/errors.db';
|
||||
|
||||
export const errorHandler = (err: Error, req: Request, res: Response, next: NextFunction) => {
|
||||
const errorId = uuidv4();
|
||||
|
||||
// Log error with context
|
||||
logger.error(
|
||||
{
|
||||
errorId,
|
||||
err,
|
||||
path: req.path,
|
||||
method: req.method,
|
||||
userId: req.user?.user_id,
|
||||
},
|
||||
'Request error',
|
||||
);
|
||||
|
||||
// Map error types to HTTP responses
|
||||
if (err instanceof ValidationError) {
|
||||
return res.status(400).json({
|
||||
success: false,
|
||||
error: { code: 'VALIDATION_ERROR', message: err.message, details: err.errors },
|
||||
meta: { errorId },
|
||||
});
|
||||
}
|
||||
|
||||
if (err instanceof NotFoundError) {
|
||||
return res.status(404).json({
|
||||
success: false,
|
||||
error: { code: 'NOT_FOUND', message: err.message },
|
||||
meta: { errorId },
|
||||
});
|
||||
}
|
||||
|
||||
if (err instanceof UniqueConstraintError) {
|
||||
return res.status(409).json({
|
||||
success: false,
|
||||
error: { code: 'CONFLICT', message: err.message },
|
||||
meta: { errorId },
|
||||
});
|
||||
}
|
||||
|
||||
// Default: Internal Server Error
|
||||
return res.status(500).json({
|
||||
success: false,
|
||||
error: {
|
||||
code: 'INTERNAL_ERROR',
|
||||
message: process.env.NODE_ENV === 'production' ? 'An unexpected error occurred' : err.message,
|
||||
},
|
||||
meta: { errorId },
|
||||
});
|
||||
};
|
||||
```
|
||||
|
||||
### Request Timeout Middleware
|
||||
|
||||
```typescript
|
||||
export const requestTimeoutMiddleware = (timeout: number) => {
|
||||
return (req: Request, res: Response, next: NextFunction) => {
|
||||
res.setTimeout(timeout, () => {
|
||||
if (!res.headersSent) {
|
||||
res.status(503).json({
|
||||
success: false,
|
||||
error: { code: 'TIMEOUT', message: 'Request timed out' },
|
||||
});
|
||||
}
|
||||
});
|
||||
next();
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## Route-Level Middleware Patterns
|
||||
|
||||
### Protected Route with Validation
|
||||
|
||||
```typescript
|
||||
router.put(
|
||||
'/flyers/:flyerId',
|
||||
authenticate, // 1. Auth check
|
||||
validate(UpdateFlyerSchema), // 2. Input validation
|
||||
flyerController.update, // 3. Handler
|
||||
);
|
||||
```
|
||||
|
||||
### Admin-Only Route
|
||||
|
||||
```typescript
|
||||
router.delete(
|
||||
'/admin/users/:userId',
|
||||
authenticate, // 1. Auth check
|
||||
requireAdmin, // 2. Role check
|
||||
validate(DeleteUserSchema), // 3. Input validation
|
||||
adminController.deleteUser, // 4. Handler
|
||||
);
|
||||
```
|
||||
|
||||
### File Upload Route
|
||||
|
||||
```typescript
|
||||
router.post(
|
||||
'/flyers/upload',
|
||||
authenticate, // 1. Auth check
|
||||
uploadFlyer.array('files', 10), // 2. File handling
|
||||
validate(UploadFlyerSchema), // 3. Metadata validation
|
||||
flyerController.upload, // 4. Handler
|
||||
);
|
||||
```
|
||||
|
||||
### Public Route with Optional Auth
|
||||
|
||||
```typescript
|
||||
router.get(
|
||||
'/flyers/:flyerId',
|
||||
optionalAuth, // 1. Attach user if present
|
||||
flyerController.getById, // 2. Handler (can check req.user)
|
||||
);
|
||||
```
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- **Security**: Defense-in-depth with multiple security layers.
|
||||
- **Consistency**: Predictable request processing order.
|
||||
- **Maintainability**: Clear separation of concerns.
|
||||
- **Debuggability**: Errors caught and logged centrally.
|
||||
- **Flexibility**: Per-route middleware composition.
|
||||
|
||||
### Negative
|
||||
|
||||
- **Order Sensitivity**: Middleware order bugs can be subtle.
|
||||
- **Performance**: Many middleware layers add latency.
|
||||
- **Complexity**: New developers must understand the pipeline.
|
||||
|
||||
### Mitigation
|
||||
|
||||
- Document middleware order in comments (as shown above).
|
||||
- Use integration tests that verify middleware chain behavior.
|
||||
- Profile middleware performance in production.
|
||||
|
||||
## Key Files
|
||||
|
||||
- `src/server.ts` - Global middleware registration
|
||||
- `src/middleware/validation.middleware.ts` - Zod validation
|
||||
- `src/middleware/fileUpload.middleware.ts` - Multer configuration
|
||||
- `src/middleware/multer.middleware.ts` - File upload handling
|
||||
- `src/middleware/errorHandler.middleware.ts` - Error handling (implicit)
|
||||
|
||||
## Related ADRs
|
||||
|
||||
- [ADR-001](./0001-standardized-error-handling.md) - Error Handling
|
||||
- [ADR-003](./0003-standardized-input-validation-using-middleware.md) - Input Validation
|
||||
- [ADR-016](./0016-api-security-hardening.md) - API Security
|
||||
- [ADR-032](./0032-rate-limiting-strategy.md) - Rate Limiting
|
||||
- [ADR-033](./0033-file-upload-and-storage-strategy.md) - File Uploads
|
||||
275
docs/adr/0044-frontend-feature-organization.md
Normal file
275
docs/adr/0044-frontend-feature-organization.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# ADR-044: Frontend Feature Organization Pattern
|
||||
|
||||
**Date**: 2026-01-09
|
||||
|
||||
**Status**: Accepted
|
||||
|
||||
**Implemented**: 2026-01-09
|
||||
|
||||
## Context
|
||||
|
||||
The React frontend has grown to include multiple distinct features:
|
||||
|
||||
- Flyer viewing and management
|
||||
- Shopping list creation
|
||||
- Budget tracking and charts
|
||||
- Voice assistant
|
||||
- User personalization
|
||||
- Admin dashboard
|
||||
|
||||
Without clear organization, code becomes scattered across generic folders (`/components`, `/hooks`, `/utils`), making it hard to:
|
||||
|
||||
1. Understand feature boundaries
|
||||
2. Find related code
|
||||
3. Refactor or remove features
|
||||
4. Onboard new developers
|
||||
|
||||
## Decision
|
||||
|
||||
We will adopt a **feature-based folder structure** where each major feature is self-contained in its own directory under `/features`. Shared code lives in dedicated top-level folders.
|
||||
|
||||
### Design Principles
|
||||
|
||||
- **Colocation**: Keep related code together (components, hooks, types, utils).
|
||||
- **Feature Independence**: Features should minimize cross-dependencies.
|
||||
- **Shared Extraction**: Only extract to shared folders when truly reused.
|
||||
- **Flat Within Features**: Avoid deep nesting within feature folders.
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── features/ # Feature modules
|
||||
│ ├── flyer/ # Flyer viewing/management
|
||||
│ │ ├── components/
|
||||
│ │ ├── hooks/
|
||||
│ │ ├── types.ts
|
||||
│ │ └── index.ts
|
||||
│ ├── shopping/ # Shopping lists
|
||||
│ │ ├── components/
|
||||
│ │ ├── hooks/
|
||||
│ │ └── index.ts
|
||||
│ ├── charts/ # Budget/analytics charts
|
||||
│ │ ├── components/
|
||||
│ │ └── index.ts
|
||||
│ ├── voice-assistant/ # Voice commands
|
||||
│ │ ├── components/
|
||||
│ │ └── index.ts
|
||||
│ └── admin/ # Admin dashboard
|
||||
│ ├── components/
|
||||
│ └── index.ts
|
||||
├── components/ # Shared UI components
|
||||
│ ├── ui/ # Primitive components (Button, Input, etc.)
|
||||
│ ├── layout/ # Layout components (Header, Footer, etc.)
|
||||
│ └── common/ # Shared composite components
|
||||
├── hooks/ # Shared hooks
|
||||
│ ├── queries/ # TanStack Query hooks
|
||||
│ ├── mutations/ # TanStack Mutation hooks
|
||||
│ └── utils/ # Utility hooks (useDebounce, etc.)
|
||||
├── providers/ # React context providers
|
||||
│ ├── AppProviders.tsx
|
||||
│ ├── UserDataProvider.tsx
|
||||
│ └── FlyersProvider.tsx
|
||||
├── pages/ # Route page components
|
||||
├── services/ # API clients, external services
|
||||
├── types/ # Shared TypeScript types
|
||||
├── utils/ # Shared utility functions
|
||||
└── lib/ # Third-party library wrappers
|
||||
```
|
||||
|
||||
### Feature Module Structure
|
||||
|
||||
Each feature follows a consistent internal structure:
|
||||
|
||||
```
|
||||
features/flyer/
|
||||
├── components/
|
||||
│ ├── FlyerCard.tsx
|
||||
│ ├── FlyerGrid.tsx
|
||||
│ ├── FlyerUploader.tsx
|
||||
│ ├── FlyerItemList.tsx
|
||||
│ └── index.ts # Re-exports all components
|
||||
├── hooks/
|
||||
│ ├── useFlyerDetails.ts
|
||||
│ ├── useFlyerUpload.ts
|
||||
│ └── index.ts # Re-exports all hooks
|
||||
├── types.ts # Feature-specific types
|
||||
├── utils.ts # Feature-specific utilities
|
||||
└── index.ts # Public API of the feature
|
||||
```
|
||||
|
||||
### Feature Index File
|
||||
|
||||
Each feature has an `index.ts` that defines its public API:
|
||||
|
||||
```typescript
|
||||
// features/flyer/index.ts
|
||||
export { FlyerCard, FlyerGrid, FlyerUploader } from './components';
|
||||
export { useFlyerDetails, useFlyerUpload } from './hooks';
|
||||
export type { FlyerViewProps, FlyerUploadState } from './types';
|
||||
```
|
||||
|
||||
### Import Patterns
|
||||
|
||||
```typescript
|
||||
// Importing from a feature (preferred)
|
||||
import { FlyerCard, useFlyerDetails } from '@/features/flyer';
|
||||
|
||||
// Importing shared components
|
||||
import { Button, Card } from '@/components/ui';
|
||||
import { useDebounce } from '@/hooks/utils';
|
||||
|
||||
// Avoid: reaching into feature internals
|
||||
// import { FlyerCard } from '@/features/flyer/components/FlyerCard';
|
||||
```
|
||||
|
||||
### Provider Organization
|
||||
|
||||
Located in `src/providers/`:
|
||||
|
||||
```typescript
|
||||
// AppProviders.tsx - Composes all providers
|
||||
export function AppProviders({ children }: { children: React.ReactNode }) {
|
||||
return (
|
||||
<QueryClientProvider client={queryClient}>
|
||||
<AuthProvider>
|
||||
<UserDataProvider>
|
||||
<FlyersProvider>
|
||||
<ThemeProvider>
|
||||
{children}
|
||||
</ThemeProvider>
|
||||
</FlyersProvider>
|
||||
</UserDataProvider>
|
||||
</AuthProvider>
|
||||
</QueryClientProvider>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Query/Mutation Hook Organization
|
||||
|
||||
Located in `src/hooks/`:
|
||||
|
||||
```typescript
|
||||
// hooks/queries/useFlyersQuery.ts
|
||||
export function useFlyersQuery(options?: { storeId?: number }) {
|
||||
return useQuery({
|
||||
queryKey: ['flyers', options],
|
||||
queryFn: () => flyerService.getFlyers(options),
|
||||
staleTime: 5 * 60 * 1000,
|
||||
});
|
||||
}
|
||||
|
||||
// hooks/mutations/useFlyerUploadMutation.ts
|
||||
export function useFlyerUploadMutation() {
|
||||
const queryClient = useQueryClient();
|
||||
|
||||
return useMutation({
|
||||
mutationFn: flyerService.uploadFlyer,
|
||||
onSuccess: () => {
|
||||
queryClient.invalidateQueries({ queryKey: ['flyers'] });
|
||||
},
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Page Components
|
||||
|
||||
Pages are thin wrappers that compose feature components:
|
||||
|
||||
```typescript
|
||||
// pages/Flyers.tsx
|
||||
import { FlyerGrid, FlyerUploader } from '@/features/flyer';
|
||||
import { PageLayout } from '@/components/layout';
|
||||
|
||||
export function FliversPage() {
|
||||
return (
|
||||
<PageLayout title="My Flyers">
|
||||
<FlyerUploader />
|
||||
<FlyerGrid />
|
||||
</PageLayout>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Cross-Feature Communication
|
||||
|
||||
When features need to communicate, use:
|
||||
|
||||
1. **Shared State Providers**: For global state (user, theme).
|
||||
2. **Query Invalidation**: For data synchronization.
|
||||
3. **Event Bus**: For loose coupling (see ADR-036).
|
||||
|
||||
```typescript
|
||||
// Feature A triggers update
|
||||
const uploadMutation = useFlyerUploadMutation();
|
||||
await uploadMutation.mutateAsync(file);
|
||||
// Query invalidation automatically updates Feature B's flyer list
|
||||
```
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
| Item | Convention | Example |
|
||||
| -------------- | -------------------- | -------------------- |
|
||||
| Feature folder | kebab-case | `voice-assistant/` |
|
||||
| Component file | PascalCase | `FlyerCard.tsx` |
|
||||
| Hook file | camelCase with `use` | `useFlyerDetails.ts` |
|
||||
| Type file | lowercase | `types.ts` |
|
||||
| Utility file | lowercase | `utils.ts` |
|
||||
| Index file | lowercase | `index.ts` |
|
||||
|
||||
## When to Create a New Feature
|
||||
|
||||
Create a new feature folder when:
|
||||
|
||||
1. The functionality is distinct and self-contained.
|
||||
2. It has its own set of components, hooks, and potentially types.
|
||||
3. It could theoretically be extracted into a separate package.
|
||||
4. It has minimal dependencies on other features.
|
||||
|
||||
Do NOT create a feature folder for:
|
||||
|
||||
- A single reusable component (use `components/`).
|
||||
- A single utility function (use `utils/`).
|
||||
- A single hook (use `hooks/`).
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- **Discoverability**: Easy to find all code related to a feature.
|
||||
- **Encapsulation**: Features have clear boundaries and public APIs.
|
||||
- **Refactoring**: Can modify or remove features with confidence.
|
||||
- **Scalability**: Supports team growth with feature ownership.
|
||||
- **Testing**: Can test features in isolation.
|
||||
|
||||
### Negative
|
||||
|
||||
- **Duplication Risk**: Similar utilities might be duplicated across features.
|
||||
- **Decision Overhead**: Must decide when to extract to shared folders.
|
||||
- **Import Verbosity**: Feature imports can be longer.
|
||||
|
||||
### Mitigation
|
||||
|
||||
- Regular refactoring sessions to extract shared code.
|
||||
- Lint rules to prevent importing from feature internals.
|
||||
- Code review focus on proper feature boundaries.
|
||||
|
||||
## Key Directories
|
||||
|
||||
- `src/features/flyer/` - Flyer viewing and management
|
||||
- `src/features/shopping/` - Shopping list functionality
|
||||
- `src/features/charts/` - Budget and analytics charts
|
||||
- `src/features/voice-assistant/` - Voice command interface
|
||||
- `src/features/admin/` - Admin dashboard
|
||||
- `src/components/ui/` - Shared primitive components
|
||||
- `src/hooks/queries/` - TanStack Query hooks
|
||||
- `src/providers/` - React context providers
|
||||
|
||||
## Related ADRs
|
||||
|
||||
- [ADR-005](./0005-frontend-state-management-and-server-cache-strategy.md) - State Management
|
||||
- [ADR-012](./0012-frontend-component-library-and-design-system.md) - Component Library
|
||||
- [ADR-026](./0026-standardized-client-side-structured-logging.md) - Client Logging
|
||||
350
docs/adr/0045-test-data-factories-and-fixtures.md
Normal file
350
docs/adr/0045-test-data-factories-and-fixtures.md
Normal file
@@ -0,0 +1,350 @@
|
||||
# ADR-045: Test Data Factories and Fixtures
|
||||
|
||||
**Date**: 2026-01-09
|
||||
|
||||
**Status**: Accepted
|
||||
|
||||
**Implemented**: 2026-01-09
|
||||
|
||||
## Context
|
||||
|
||||
The application has a complex domain model with many entity types:
|
||||
|
||||
- Users, Profiles, Addresses
|
||||
- Flyers, FlyerItems, Stores
|
||||
- ShoppingLists, ShoppingListItems
|
||||
- Recipes, RecipeIngredients
|
||||
- Gamification (points, badges, leaderboards)
|
||||
- And more...
|
||||
|
||||
Testing requires realistic mock data that:
|
||||
|
||||
1. Satisfies TypeScript types.
|
||||
2. Has valid relationships between entities.
|
||||
3. Is customizable for specific test scenarios.
|
||||
4. Is consistent across test suites.
|
||||
5. Avoids boilerplate in test files.
|
||||
|
||||
## Decision
|
||||
|
||||
We will implement a **factory function pattern** for test data generation:
|
||||
|
||||
1. **Centralized Mock Factories**: All factories in a single, organized file.
|
||||
2. **Sensible Defaults**: Each factory produces valid data with minimal input.
|
||||
3. **Override Support**: Factories accept partial overrides for customization.
|
||||
4. **Relationship Helpers**: Factories can generate related entities.
|
||||
5. **Type Safety**: Factories return properly typed objects.
|
||||
|
||||
### Design Principles
|
||||
|
||||
- **Convention over Configuration**: Factories work with zero arguments.
|
||||
- **Composability**: Factories can call other factories.
|
||||
- **Immutability**: Each call returns a new object (no shared references).
|
||||
- **Predictability**: Deterministic output when seeded.
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Factory File Structure
|
||||
|
||||
Located in `src/test/mockFactories.ts`:
|
||||
|
||||
```typescript
|
||||
import { v4 as uuidv4 } from 'uuid';
|
||||
import type {
|
||||
User,
|
||||
UserProfile,
|
||||
Flyer,
|
||||
FlyerItem,
|
||||
ShoppingList,
|
||||
// ... other types
|
||||
} from '../types';
|
||||
|
||||
// ============================================
|
||||
// PRIMITIVE HELPERS
|
||||
// ============================================
|
||||
let idCounter = 1;
|
||||
export const nextId = () => idCounter++;
|
||||
export const resetIdCounter = () => {
|
||||
idCounter = 1;
|
||||
};
|
||||
|
||||
export const randomEmail = () => `user-${uuidv4().slice(0, 8)}@test.com`;
|
||||
export const randomDate = (daysAgo = 0) => {
|
||||
const date = new Date();
|
||||
date.setDate(date.getDate() - daysAgo);
|
||||
return date.toISOString();
|
||||
};
|
||||
|
||||
// ============================================
|
||||
// USER FACTORIES
|
||||
// ============================================
|
||||
export const createMockUser = (overrides: Partial<User> = {}): User => ({
|
||||
user_id: nextId(),
|
||||
email: randomEmail(),
|
||||
name: 'Test User',
|
||||
role: 'user',
|
||||
created_at: randomDate(30),
|
||||
updated_at: randomDate(),
|
||||
...overrides,
|
||||
});
|
||||
|
||||
export const createMockUserProfile = (overrides: Partial<UserProfile> = {}): UserProfile => {
|
||||
const user = createMockUser(overrides.user);
|
||||
return {
|
||||
user,
|
||||
profile: createMockProfile({ user_id: user.user_id, ...overrides.profile }),
|
||||
address: overrides.address ?? null,
|
||||
preferences: overrides.preferences ?? null,
|
||||
};
|
||||
};
|
||||
|
||||
// ============================================
|
||||
// FLYER FACTORIES
|
||||
// ============================================
|
||||
export const createMockFlyer = (overrides: Partial<Flyer> = {}): Flyer => ({
|
||||
flyer_id: nextId(),
|
||||
file_name: 'test-flyer.jpg',
|
||||
image_url: 'https://example.com/flyer.jpg',
|
||||
icon_url: 'https://example.com/flyer-icon.jpg',
|
||||
checksum: uuidv4(),
|
||||
store_name: 'Test Store',
|
||||
store_address: '123 Test St',
|
||||
valid_from: randomDate(7),
|
||||
valid_to: randomDate(-7), // 7 days in future
|
||||
item_count: 10,
|
||||
status: 'approved',
|
||||
uploaded_by: null,
|
||||
created_at: randomDate(7),
|
||||
updated_at: randomDate(),
|
||||
...overrides,
|
||||
});
|
||||
|
||||
export const createMockFlyerItem = (overrides: Partial<FlyerItem> = {}): FlyerItem => ({
|
||||
flyer_item_id: nextId(),
|
||||
flyer_id: overrides.flyer_id ?? nextId(),
|
||||
item: 'Test Product',
|
||||
price_display: '$2.99',
|
||||
price_in_cents: 299,
|
||||
quantity: 'each',
|
||||
category_name: 'Groceries',
|
||||
master_item_id: null,
|
||||
view_count: 0,
|
||||
click_count: 0,
|
||||
created_at: randomDate(7),
|
||||
updated_at: randomDate(),
|
||||
...overrides,
|
||||
});
|
||||
|
||||
// ============================================
|
||||
// FLYER WITH ITEMS (COMPOSITE)
|
||||
// ============================================
|
||||
export const createMockFlyerWithItems = (
|
||||
flyerOverrides: Partial<Flyer> = {},
|
||||
itemCount = 5,
|
||||
): { flyer: Flyer; items: FlyerItem[] } => {
|
||||
const flyer = createMockFlyer(flyerOverrides);
|
||||
const items = Array.from({ length: itemCount }, (_, i) =>
|
||||
createMockFlyerItem({
|
||||
flyer_id: flyer.flyer_id,
|
||||
item: `Product ${i + 1}`,
|
||||
price_in_cents: 100 + i * 50,
|
||||
}),
|
||||
);
|
||||
flyer.item_count = items.length;
|
||||
return { flyer, items };
|
||||
};
|
||||
|
||||
// ============================================
|
||||
// SHOPPING LIST FACTORIES
|
||||
// ============================================
|
||||
export const createMockShoppingList = (overrides: Partial<ShoppingList> = {}): ShoppingList => ({
|
||||
shopping_list_id: nextId(),
|
||||
user_id: overrides.user_id ?? nextId(),
|
||||
name: 'Weekly Groceries',
|
||||
is_active: true,
|
||||
created_at: randomDate(14),
|
||||
updated_at: randomDate(),
|
||||
...overrides,
|
||||
});
|
||||
|
||||
export const createMockShoppingListItem = (
|
||||
overrides: Partial<ShoppingListItem> = {},
|
||||
): ShoppingListItem => ({
|
||||
shopping_list_item_id: nextId(),
|
||||
shopping_list_id: overrides.shopping_list_id ?? nextId(),
|
||||
item_name: 'Milk',
|
||||
quantity: 1,
|
||||
is_purchased: false,
|
||||
created_at: randomDate(7),
|
||||
updated_at: randomDate(),
|
||||
...overrides,
|
||||
});
|
||||
```
|
||||
|
||||
### Usage in Tests
|
||||
|
||||
```typescript
|
||||
import {
|
||||
createMockUser,
|
||||
createMockFlyer,
|
||||
createMockFlyerWithItems,
|
||||
resetIdCounter,
|
||||
} from '../test/mockFactories';
|
||||
|
||||
describe('FlyerService', () => {
|
||||
beforeEach(() => {
|
||||
resetIdCounter(); // Consistent IDs across tests
|
||||
});
|
||||
|
||||
it('should get flyer by ID', async () => {
|
||||
const mockFlyer = createMockFlyer({ store_name: 'Walmart' });
|
||||
|
||||
mockDb.query.mockResolvedValue({ rows: [mockFlyer] });
|
||||
|
||||
const result = await flyerService.getFlyerById(mockFlyer.flyer_id);
|
||||
|
||||
expect(result.store_name).toBe('Walmart');
|
||||
});
|
||||
|
||||
it('should return flyer with items', async () => {
|
||||
const { flyer, items } = createMockFlyerWithItems(
|
||||
{ store_name: 'Costco' },
|
||||
10, // 10 items
|
||||
);
|
||||
|
||||
mockDb.query.mockResolvedValueOnce({ rows: [flyer] }).mockResolvedValueOnce({ rows: items });
|
||||
|
||||
const result = await flyerService.getFlyerWithItems(flyer.flyer_id);
|
||||
|
||||
expect(result.flyer.store_name).toBe('Costco');
|
||||
expect(result.items).toHaveLength(10);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Bulk Data Generation
|
||||
|
||||
For integration tests or seeding:
|
||||
|
||||
```typescript
|
||||
export const createMockDataset = () => {
|
||||
const users = Array.from({ length: 10 }, () => createMockUser());
|
||||
const flyers = Array.from({ length: 5 }, () => createMockFlyer());
|
||||
const flyersWithItems = flyers.map((flyer) => ({
|
||||
flyer,
|
||||
items: Array.from({ length: Math.floor(Math.random() * 20) + 5 }, () =>
|
||||
createMockFlyerItem({ flyer_id: flyer.flyer_id }),
|
||||
),
|
||||
}));
|
||||
|
||||
return { users, flyers, flyersWithItems };
|
||||
};
|
||||
```
|
||||
|
||||
### API Response Factories
|
||||
|
||||
For testing API handlers:
|
||||
|
||||
```typescript
|
||||
export const createMockApiResponse = <T>(
|
||||
data: T,
|
||||
overrides: Partial<ApiResponse<T>> = {},
|
||||
): ApiResponse<T> => ({
|
||||
success: true,
|
||||
data,
|
||||
meta: {
|
||||
timestamp: new Date().toISOString(),
|
||||
requestId: uuidv4(),
|
||||
...overrides.meta,
|
||||
},
|
||||
...overrides,
|
||||
});
|
||||
|
||||
export const createMockPaginatedResponse = <T>(
|
||||
items: T[],
|
||||
page = 1,
|
||||
pageSize = 20,
|
||||
): PaginatedApiResponse<T> => ({
|
||||
success: true,
|
||||
data: items,
|
||||
meta: {
|
||||
timestamp: new Date().toISOString(),
|
||||
requestId: uuidv4(),
|
||||
},
|
||||
pagination: {
|
||||
page,
|
||||
pageSize,
|
||||
totalItems: items.length,
|
||||
totalPages: Math.ceil(items.length / pageSize),
|
||||
hasMore: false,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Database Query Mock Helpers
|
||||
|
||||
```typescript
|
||||
export const mockQueryResult = <T>(rows: T[]) => ({
|
||||
rows,
|
||||
rowCount: rows.length,
|
||||
});
|
||||
|
||||
export const mockEmptyResult = () => ({
|
||||
rows: [],
|
||||
rowCount: 0,
|
||||
});
|
||||
|
||||
export const mockInsertResult = <T>(inserted: T) => ({
|
||||
rows: [inserted],
|
||||
rowCount: 1,
|
||||
});
|
||||
```
|
||||
|
||||
## Test Cleanup Utilities
|
||||
|
||||
```typescript
|
||||
// For integration tests with real database
|
||||
export const cleanupTestData = async (pool: Pool) => {
|
||||
await pool.query('DELETE FROM flyer_items WHERE flyer_id > 1000000');
|
||||
await pool.query('DELETE FROM flyers WHERE flyer_id > 1000000');
|
||||
await pool.query('DELETE FROM users WHERE user_id > 1000000');
|
||||
};
|
||||
|
||||
// Mark test data with high IDs
|
||||
export const createTestFlyer = (overrides: Partial<Flyer> = {}) =>
|
||||
createMockFlyer({ flyer_id: 1000000 + nextId(), ...overrides });
|
||||
```
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- **Consistency**: All tests use the same factory patterns.
|
||||
- **Type Safety**: Factories return correctly typed objects.
|
||||
- **Reduced Boilerplate**: Tests focus on behavior, not data setup.
|
||||
- **Maintainability**: Update factory once, all tests benefit.
|
||||
- **Flexibility**: Easy to create edge case data.
|
||||
|
||||
### Negative
|
||||
|
||||
- **Single Large File**: Factory file can become large.
|
||||
- **Learning Curve**: New developers must learn factory patterns.
|
||||
- **Maintenance**: Factories must be updated when types change.
|
||||
|
||||
### Mitigation
|
||||
|
||||
- Split factories into multiple files if needed (by domain).
|
||||
- Add JSDoc comments explaining each factory.
|
||||
- Use TypeScript to catch type mismatches automatically.
|
||||
|
||||
## Key Files
|
||||
|
||||
- `src/test/mockFactories.ts` - All mock factory functions
|
||||
- `src/test/testUtils.ts` - Test helper utilities
|
||||
- `src/test/setup.ts` - Global test setup with factory reset
|
||||
|
||||
## Related ADRs
|
||||
|
||||
- [ADR-010](./0010-testing-strategy-and-standards.md) - Testing Strategy
|
||||
- [ADR-040](./0040-testing-economics-and-priorities.md) - Testing Economics
|
||||
- [ADR-027](./0027-standardized-naming-convention-for-ai-and-database-types.md) - Type Naming
|
||||
363
docs/adr/0046-image-processing-pipeline.md
Normal file
363
docs/adr/0046-image-processing-pipeline.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# ADR-046: Image Processing Pipeline
|
||||
|
||||
**Date**: 2026-01-09
|
||||
|
||||
**Status**: Accepted
|
||||
|
||||
**Implemented**: 2026-01-09
|
||||
|
||||
## Context
|
||||
|
||||
The application handles significant image processing for flyer uploads:
|
||||
|
||||
1. **Privacy Protection**: Strip EXIF metadata (location, device info).
|
||||
2. **Optimization**: Resize, compress, and convert images for web delivery.
|
||||
3. **Icon Generation**: Create thumbnails for listing views.
|
||||
4. **Format Support**: Handle JPEG, PNG, WebP, and PDF inputs.
|
||||
5. **Storage Management**: Organize processed images on disk.
|
||||
|
||||
These operations must be:
|
||||
|
||||
- **Performant**: Large images should not block the request.
|
||||
- **Secure**: Prevent malicious file uploads.
|
||||
- **Consistent**: Produce predictable output quality.
|
||||
- **Testable**: Support unit testing without real files.
|
||||
|
||||
## Decision
|
||||
|
||||
We will implement a modular image processing pipeline using:
|
||||
|
||||
1. **Sharp**: For image resizing, compression, and format conversion.
|
||||
2. **EXIF Parsing**: For metadata extraction and stripping.
|
||||
3. **UUID Naming**: For unique, non-guessable file names.
|
||||
4. **Directory Structure**: Organized storage for originals and derivatives.
|
||||
|
||||
### Design Principles
|
||||
|
||||
- **Pipeline Pattern**: Chain processing steps in a predictable order.
|
||||
- **Fail-Fast Validation**: Reject invalid files before processing.
|
||||
- **Idempotent Operations**: Same input produces same output.
|
||||
- **Resource Cleanup**: Delete temp files on error.
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Image Processor Module
|
||||
|
||||
Located in `src/utils/imageProcessor.ts`:
|
||||
|
||||
```typescript
|
||||
import sharp from 'sharp';
|
||||
import path from 'path';
|
||||
import { v4 as uuidv4 } from 'uuid';
|
||||
import fs from 'fs/promises';
|
||||
import type { Logger } from 'pino';
|
||||
|
||||
// ============================================
|
||||
// CONFIGURATION
|
||||
// ============================================
|
||||
const IMAGE_CONFIG = {
|
||||
maxWidth: 2048,
|
||||
maxHeight: 2048,
|
||||
quality: 85,
|
||||
iconSize: 200,
|
||||
allowedFormats: ['jpeg', 'png', 'webp', 'avif'],
|
||||
outputFormat: 'webp' as const,
|
||||
};
|
||||
|
||||
// ============================================
|
||||
// MAIN PROCESSING FUNCTION
|
||||
// ============================================
|
||||
export async function processAndSaveImage(
|
||||
inputPath: string,
|
||||
outputDir: string,
|
||||
originalFileName: string,
|
||||
logger: Logger,
|
||||
): Promise<string> {
|
||||
const outputFileName = `${uuidv4()}.${IMAGE_CONFIG.outputFormat}`;
|
||||
const outputPath = path.join(outputDir, outputFileName);
|
||||
|
||||
logger.info({ inputPath, outputPath }, 'Processing image');
|
||||
|
||||
try {
|
||||
// Create sharp instance and strip metadata
|
||||
await sharp(inputPath)
|
||||
.rotate() // Auto-rotate based on EXIF orientation
|
||||
.resize(IMAGE_CONFIG.maxWidth, IMAGE_CONFIG.maxHeight, {
|
||||
fit: 'inside',
|
||||
withoutEnlargement: true,
|
||||
})
|
||||
.webp({ quality: IMAGE_CONFIG.quality })
|
||||
.toFile(outputPath);
|
||||
|
||||
logger.info({ outputPath }, 'Image processed successfully');
|
||||
return outputFileName;
|
||||
} catch (error) {
|
||||
logger.error({ error, inputPath }, 'Image processing failed');
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Icon Generation
|
||||
|
||||
```typescript
|
||||
export async function generateFlyerIcon(
|
||||
inputPath: string,
|
||||
iconsDir: string,
|
||||
logger: Logger,
|
||||
): Promise<string> {
|
||||
// Ensure icons directory exists
|
||||
await fs.mkdir(iconsDir, { recursive: true });
|
||||
|
||||
const iconFileName = `${uuidv4()}-icon.webp`;
|
||||
const iconPath = path.join(iconsDir, iconFileName);
|
||||
|
||||
logger.info({ inputPath, iconPath }, 'Generating icon');
|
||||
|
||||
await sharp(inputPath)
|
||||
.resize(IMAGE_CONFIG.iconSize, IMAGE_CONFIG.iconSize, {
|
||||
fit: 'cover',
|
||||
position: 'top', // Flyers usually have store name at top
|
||||
})
|
||||
.webp({ quality: 80 })
|
||||
.toFile(iconPath);
|
||||
|
||||
logger.info({ iconPath }, 'Icon generated successfully');
|
||||
return iconFileName;
|
||||
}
|
||||
```
|
||||
|
||||
### EXIF Metadata Extraction
|
||||
|
||||
For audit/logging purposes before stripping:
|
||||
|
||||
```typescript
|
||||
import ExifParser from 'exif-parser';
|
||||
|
||||
export async function extractExifMetadata(
|
||||
filePath: string,
|
||||
logger: Logger,
|
||||
): Promise<ExifMetadata | null> {
|
||||
try {
|
||||
const buffer = await fs.readFile(filePath);
|
||||
const parser = ExifParser.create(buffer);
|
||||
const result = parser.parse();
|
||||
|
||||
const metadata: ExifMetadata = {
|
||||
make: result.tags?.Make,
|
||||
model: result.tags?.Model,
|
||||
dateTime: result.tags?.DateTimeOriginal,
|
||||
gpsLatitude: result.tags?.GPSLatitude,
|
||||
gpsLongitude: result.tags?.GPSLongitude,
|
||||
orientation: result.tags?.Orientation,
|
||||
};
|
||||
|
||||
// Log if GPS data was present (privacy concern)
|
||||
if (metadata.gpsLatitude || metadata.gpsLongitude) {
|
||||
logger.info({ filePath }, 'GPS data found in image, will be stripped during processing');
|
||||
}
|
||||
|
||||
return metadata;
|
||||
} catch (error) {
|
||||
logger.debug({ error, filePath }, 'No EXIF data found or parsing failed');
|
||||
return null;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### PDF to Image Conversion
|
||||
|
||||
```typescript
|
||||
import * as pdfjs from 'pdfjs-dist';
|
||||
|
||||
export async function convertPdfToImages(
|
||||
pdfPath: string,
|
||||
outputDir: string,
|
||||
logger: Logger,
|
||||
): Promise<string[]> {
|
||||
const pdfData = await fs.readFile(pdfPath);
|
||||
const pdf = await pdfjs.getDocument({ data: pdfData }).promise;
|
||||
|
||||
const outputPaths: string[] = [];
|
||||
|
||||
for (let i = 1; i <= pdf.numPages; i++) {
|
||||
const page = await pdf.getPage(i);
|
||||
const viewport = page.getViewport({ scale: 2.0 }); // 2x for quality
|
||||
|
||||
// Create canvas and render
|
||||
const canvas = createCanvas(viewport.width, viewport.height);
|
||||
const context = canvas.getContext('2d');
|
||||
|
||||
await page.render({
|
||||
canvasContext: context,
|
||||
viewport: viewport,
|
||||
}).promise;
|
||||
|
||||
// Save as image
|
||||
const outputFileName = `${uuidv4()}-page-${i}.png`;
|
||||
const outputPath = path.join(outputDir, outputFileName);
|
||||
const buffer = canvas.toBuffer('image/png');
|
||||
await fs.writeFile(outputPath, buffer);
|
||||
|
||||
outputPaths.push(outputPath);
|
||||
logger.info({ page: i, outputPath }, 'PDF page converted to image');
|
||||
}
|
||||
|
||||
return outputPaths;
|
||||
}
|
||||
```
|
||||
|
||||
### File Validation
|
||||
|
||||
```typescript
|
||||
import { fileTypeFromBuffer } from 'file-type';
|
||||
|
||||
export async function validateImageFile(
|
||||
filePath: string,
|
||||
logger: Logger,
|
||||
): Promise<{ valid: boolean; mimeType: string | null; error?: string }> {
|
||||
try {
|
||||
const buffer = await fs.readFile(filePath, { length: 4100 }); // Read header only
|
||||
const type = await fileTypeFromBuffer(buffer);
|
||||
|
||||
if (!type) {
|
||||
return { valid: false, mimeType: null, error: 'Unknown file type' };
|
||||
}
|
||||
|
||||
const allowedMimes = ['image/jpeg', 'image/png', 'image/webp', 'image/avif', 'application/pdf'];
|
||||
|
||||
if (!allowedMimes.includes(type.mime)) {
|
||||
return {
|
||||
valid: false,
|
||||
mimeType: type.mime,
|
||||
error: `File type ${type.mime} not allowed`,
|
||||
};
|
||||
}
|
||||
|
||||
return { valid: true, mimeType: type.mime };
|
||||
} catch (error) {
|
||||
logger.error({ error, filePath }, 'File validation failed');
|
||||
return { valid: false, mimeType: null, error: 'Validation error' };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Storage Organization
|
||||
|
||||
```
|
||||
flyer-images/
|
||||
├── originals/ # Uploaded files (if kept)
|
||||
│ └── {uuid}.{ext}
|
||||
├── processed/ # Optimized images (or root level)
|
||||
│ └── {uuid}.webp
|
||||
├── icons/ # Thumbnails
|
||||
│ └── {uuid}-icon.webp
|
||||
└── temp/ # Temporary processing files
|
||||
└── {uuid}.tmp
|
||||
```
|
||||
|
||||
### Cleanup Utilities
|
||||
|
||||
```typescript
|
||||
export async function cleanupTempFiles(
|
||||
tempDir: string,
|
||||
maxAgeMs: number,
|
||||
logger: Logger,
|
||||
): Promise<number> {
|
||||
const files = await fs.readdir(tempDir);
|
||||
const now = Date.now();
|
||||
let deletedCount = 0;
|
||||
|
||||
for (const file of files) {
|
||||
const filePath = path.join(tempDir, file);
|
||||
const stats = await fs.stat(filePath);
|
||||
const age = now - stats.mtimeMs;
|
||||
|
||||
if (age > maxAgeMs) {
|
||||
await fs.unlink(filePath);
|
||||
deletedCount++;
|
||||
}
|
||||
}
|
||||
|
||||
logger.info({ deletedCount, tempDir }, 'Cleaned up temp files');
|
||||
return deletedCount;
|
||||
}
|
||||
```
|
||||
|
||||
### Integration with Flyer Processing
|
||||
|
||||
```typescript
|
||||
// In flyerProcessingService.ts
|
||||
export async function processUploadedFlyer(
|
||||
file: Express.Multer.File,
|
||||
logger: Logger,
|
||||
): Promise<{ imageUrl: string; iconUrl: string }> {
|
||||
const flyerImageDir = 'flyer-images';
|
||||
const iconsDir = path.join(flyerImageDir, 'icons');
|
||||
|
||||
// 1. Validate file
|
||||
const validation = await validateImageFile(file.path, logger);
|
||||
if (!validation.valid) {
|
||||
throw new ValidationError([{ path: 'file', message: validation.error! }]);
|
||||
}
|
||||
|
||||
// 2. Extract and log EXIF before stripping
|
||||
await extractExifMetadata(file.path, logger);
|
||||
|
||||
// 3. Process and optimize image
|
||||
const processedFileName = await processAndSaveImage(
|
||||
file.path,
|
||||
flyerImageDir,
|
||||
file.originalname,
|
||||
logger,
|
||||
);
|
||||
|
||||
// 4. Generate icon
|
||||
const processedImagePath = path.join(flyerImageDir, processedFileName);
|
||||
const iconFileName = await generateFlyerIcon(processedImagePath, iconsDir, logger);
|
||||
|
||||
// 5. Construct URLs
|
||||
const baseUrl = process.env.BACKEND_URL || 'http://localhost:3001';
|
||||
const imageUrl = `${baseUrl}/flyer-images/${processedFileName}`;
|
||||
const iconUrl = `${baseUrl}/flyer-images/icons/${iconFileName}`;
|
||||
|
||||
// 6. Delete original upload (privacy)
|
||||
await fs.unlink(file.path);
|
||||
|
||||
return { imageUrl, iconUrl };
|
||||
}
|
||||
```
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- **Privacy**: EXIF metadata (including GPS) is stripped automatically.
|
||||
- **Performance**: WebP output reduces file sizes by 25-35%.
|
||||
- **Consistency**: All images processed to standard format and dimensions.
|
||||
- **Security**: File type validation prevents malicious uploads.
|
||||
- **Organization**: Clear directory structure for storage management.
|
||||
|
||||
### Negative
|
||||
|
||||
- **CPU Intensive**: Image processing can be slow for large files.
|
||||
- **Storage**: Keeping originals doubles storage requirements.
|
||||
- **Dependency**: Sharp requires native binaries.
|
||||
|
||||
### Mitigation
|
||||
|
||||
- Process images in background jobs (BullMQ queue).
|
||||
- Configure whether to keep originals based on requirements.
|
||||
- Use pre-built Sharp binaries via npm.
|
||||
|
||||
## Key Files
|
||||
|
||||
- `src/utils/imageProcessor.ts` - Core image processing functions
|
||||
- `src/services/flyer/flyerProcessingService.ts` - Integration with flyer workflow
|
||||
- `src/middleware/fileUpload.middleware.ts` - Multer configuration
|
||||
|
||||
## Related ADRs
|
||||
|
||||
- [ADR-033](./0033-file-upload-and-storage-strategy.md) - File Upload Strategy
|
||||
- [ADR-006](./0006-background-job-processing-and-task-queues.md) - Background Jobs
|
||||
- [ADR-041](./0041-ai-gemini-integration-architecture.md) - AI Integration (uses processed images)
|
||||
545
docs/adr/0047-project-file-and-folder-organization.md
Normal file
545
docs/adr/0047-project-file-and-folder-organization.md
Normal file
@@ -0,0 +1,545 @@
|
||||
# ADR-047: Project File and Folder Organization
|
||||
|
||||
**Date**: 2026-01-09
|
||||
|
||||
**Status**: Proposed
|
||||
|
||||
**Effort**: XL (Major reorganization across entire codebase)
|
||||
|
||||
## Context
|
||||
|
||||
The project has grown organically with a mix of organizational patterns:
|
||||
|
||||
- **By Type**: Components, hooks, middleware, utilities, types all in flat directories
|
||||
- **By Feature**: Routes, database modules, and partial feature directories
|
||||
- **Mixed Concerns**: Frontend and backend code intermingled in `src/`
|
||||
|
||||
Current pain points:
|
||||
|
||||
1. **Flat services directory**: 75+ files with no subdirectory grouping
|
||||
2. **Monolithic types.ts**: 750+ lines, unclear when to add new types
|
||||
3. **Flat components directory**: 43+ components at root level
|
||||
4. **Incomplete feature modules**: Features contain only UI, not domain logic
|
||||
5. **No clear frontend/backend separation**: Both share `src/` root
|
||||
|
||||
As the project scales, these issues compound, making navigation, refactoring, and onboarding increasingly difficult.
|
||||
|
||||
## Decision
|
||||
|
||||
We will adopt a **domain-driven organization** with clear separation between:
|
||||
|
||||
1. **Client code** (React, browser-only)
|
||||
2. **Server code** (Express, Node-only)
|
||||
3. **Shared code** (Types, utilities used by both)
|
||||
|
||||
Within each layer, organize by **feature/domain** rather than by file type.
|
||||
|
||||
### Design Principles
|
||||
|
||||
- **Colocation**: Related code lives together (components, hooks, types, tests)
|
||||
- **Explicit Boundaries**: Clear separation between client, server, and shared
|
||||
- **Feature Ownership**: Each domain owns its entire vertical slice
|
||||
- **Discoverability**: New developers can find code by thinking about features, not file types
|
||||
- **Incremental Migration**: Structure supports gradual transition from current layout
|
||||
|
||||
## Target Directory Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── client/ # React frontend (browser-only code)
|
||||
│ ├── app/ # App shell and routing
|
||||
│ │ ├── App.tsx
|
||||
│ │ ├── routes.tsx
|
||||
│ │ └── providers/ # React context providers
|
||||
│ │ ├── AppProviders.tsx
|
||||
│ │ ├── AuthProvider.tsx
|
||||
│ │ ├── FlyersProvider.tsx
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ ├── features/ # Feature modules (UI + hooks + types)
|
||||
│ │ ├── auth/
|
||||
│ │ │ ├── components/
|
||||
│ │ │ │ ├── LoginForm.tsx
|
||||
│ │ │ │ ├── RegisterForm.tsx
|
||||
│ │ │ │ └── index.ts
|
||||
│ │ │ ├── hooks/
|
||||
│ │ │ │ ├── useAuth.ts
|
||||
│ │ │ │ ├── useLogin.ts
|
||||
│ │ │ │ └── index.ts
|
||||
│ │ │ ├── types.ts
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── flyer/
|
||||
│ │ │ ├── components/
|
||||
│ │ │ │ ├── FlyerCard.tsx
|
||||
│ │ │ │ ├── FlyerGrid.tsx
|
||||
│ │ │ │ ├── FlyerUploader.tsx
|
||||
│ │ │ │ ├── BulkImporter.tsx
|
||||
│ │ │ │ └── index.ts
|
||||
│ │ │ ├── hooks/
|
||||
│ │ │ │ ├── useFlyersQuery.ts
|
||||
│ │ │ │ ├── useFlyerUploadMutation.ts
|
||||
│ │ │ │ └── index.ts
|
||||
│ │ │ ├── types.ts
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── shopping/
|
||||
│ │ │ ├── components/
|
||||
│ │ │ ├── hooks/
|
||||
│ │ │ ├── types.ts
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── recipes/
|
||||
│ │ │ ├── components/
|
||||
│ │ │ ├── hooks/
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── charts/
|
||||
│ │ │ ├── components/
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── voice-assistant/
|
||||
│ │ │ ├── components/
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── user/
|
||||
│ │ │ ├── components/
|
||||
│ │ │ ├── hooks/
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── gamification/
|
||||
│ │ │ ├── components/
|
||||
│ │ │ ├── hooks/
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ └── admin/
|
||||
│ │ ├── components/
|
||||
│ │ ├── hooks/
|
||||
│ │ ├── pages/ # Admin-specific pages
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ ├── pages/ # Route page components
|
||||
│ │ ├── HomePage.tsx
|
||||
│ │ ├── MyDealsPage.tsx
|
||||
│ │ ├── UserProfilePage.tsx
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ ├── components/ # Shared UI components
|
||||
│ │ ├── ui/ # Primitive components (design system)
|
||||
│ │ │ ├── Button.tsx
|
||||
│ │ │ ├── Card.tsx
|
||||
│ │ │ ├── Input.tsx
|
||||
│ │ │ ├── Modal.tsx
|
||||
│ │ │ ├── Badge.tsx
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── layout/ # Layout components
|
||||
│ │ │ ├── Header.tsx
|
||||
│ │ │ ├── Footer.tsx
|
||||
│ │ │ ├── Sidebar.tsx
|
||||
│ │ │ ├── PageLayout.tsx
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── feedback/ # User feedback components
|
||||
│ │ │ ├── LoadingSpinner.tsx
|
||||
│ │ │ ├── ErrorMessage.tsx
|
||||
│ │ │ ├── Toast.tsx
|
||||
│ │ │ ├── ConfirmDialog.tsx
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── forms/ # Form components
|
||||
│ │ │ ├── FormField.tsx
|
||||
│ │ │ ├── SearchInput.tsx
|
||||
│ │ │ ├── DatePicker.tsx
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── icons/ # Icon components
|
||||
│ │ │ ├── ChevronIcon.tsx
|
||||
│ │ │ ├── UserIcon.tsx
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ ├── hooks/ # Shared hooks (not feature-specific)
|
||||
│ │ ├── useDebounce.ts
|
||||
│ │ ├── useLocalStorage.ts
|
||||
│ │ ├── useMediaQuery.ts
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ ├── services/ # Client-side services (API clients)
|
||||
│ │ ├── apiClient.ts
|
||||
│ │ ├── logger.client.ts
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ ├── lib/ # Third-party library wrappers
|
||||
│ │ ├── queryClient.ts
|
||||
│ │ ├── toast.ts
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ └── styles/ # Global styles
|
||||
│ ├── globals.css
|
||||
│ └── tailwind.css
|
||||
│
|
||||
├── server/ # Express backend (Node-only code)
|
||||
│ ├── app.ts # Express app setup
|
||||
│ ├── server.ts # Server entry point
|
||||
│ │
|
||||
│ ├── domains/ # Domain modules (business logic)
|
||||
│ │ ├── auth/
|
||||
│ │ │ ├── auth.service.ts
|
||||
│ │ │ ├── auth.routes.ts
|
||||
│ │ │ ├── auth.controller.ts
|
||||
│ │ │ ├── auth.repository.ts
|
||||
│ │ │ ├── auth.types.ts
|
||||
│ │ │ ├── auth.service.test.ts
|
||||
│ │ │ ├── auth.routes.test.ts
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── flyer/
|
||||
│ │ │ ├── flyer.service.ts
|
||||
│ │ │ ├── flyer.routes.ts
|
||||
│ │ │ ├── flyer.controller.ts
|
||||
│ │ │ ├── flyer.repository.ts
|
||||
│ │ │ ├── flyer.types.ts
|
||||
│ │ │ ├── flyer.processing.ts # Flyer-specific processing logic
|
||||
│ │ │ ├── flyer.ai.ts # AI integration for flyers
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── user/
|
||||
│ │ │ ├── user.service.ts
|
||||
│ │ │ ├── user.routes.ts
|
||||
│ │ │ ├── user.controller.ts
|
||||
│ │ │ ├── user.repository.ts
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── shopping/
|
||||
│ │ │ ├── shopping.service.ts
|
||||
│ │ │ ├── shopping.routes.ts
|
||||
│ │ │ ├── shopping.repository.ts
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── recipe/
|
||||
│ │ │ ├── recipe.service.ts
|
||||
│ │ │ ├── recipe.routes.ts
|
||||
│ │ │ ├── recipe.repository.ts
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── gamification/
|
||||
│ │ │ ├── gamification.service.ts
|
||||
│ │ │ ├── gamification.routes.ts
|
||||
│ │ │ ├── gamification.repository.ts
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── notification/
|
||||
│ │ │ ├── notification.service.ts
|
||||
│ │ │ ├── email.service.ts
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── ai/
|
||||
│ │ │ ├── ai.service.ts
|
||||
│ │ │ ├── ai.client.ts
|
||||
│ │ │ ├── ai.prompts.ts
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ └── admin/
|
||||
│ │ ├── admin.routes.ts
|
||||
│ │ ├── admin.controller.ts
|
||||
│ │ ├── admin.service.ts
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ ├── middleware/ # Express middleware
|
||||
│ │ ├── auth.middleware.ts
|
||||
│ │ ├── validation.middleware.ts
|
||||
│ │ ├── errorHandler.middleware.ts
|
||||
│ │ ├── rateLimit.middleware.ts
|
||||
│ │ ├── fileUpload.middleware.ts
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ ├── infrastructure/ # Cross-cutting infrastructure
|
||||
│ │ ├── database/
|
||||
│ │ │ ├── pool.ts
|
||||
│ │ │ ├── migrations/
|
||||
│ │ │ └── seeds/
|
||||
│ │ │
|
||||
│ │ ├── cache/
|
||||
│ │ │ ├── redis.ts
|
||||
│ │ │ └── cacheService.ts
|
||||
│ │ │
|
||||
│ │ ├── queue/
|
||||
│ │ │ ├── queueService.ts
|
||||
│ │ │ ├── workers/
|
||||
│ │ │ │ ├── email.worker.ts
|
||||
│ │ │ │ ├── flyer.worker.ts
|
||||
│ │ │ │ └── index.ts
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── jobs/
|
||||
│ │ │ ├── cronJobs.ts
|
||||
│ │ │ ├── dailyAnalytics.job.ts
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ └── logging/
|
||||
│ │ ├── logger.ts
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ ├── config/ # Server configuration
|
||||
│ │ ├── database.config.ts
|
||||
│ │ ├── redis.config.ts
|
||||
│ │ ├── auth.config.ts
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ └── utils/ # Server-only utilities
|
||||
│ ├── imageProcessor.ts
|
||||
│ ├── geocoding.ts
|
||||
│ └── index.ts
|
||||
│
|
||||
├── shared/ # Code shared between client and server
|
||||
│ ├── types/ # Shared TypeScript types
|
||||
│ │ ├── entities/ # Domain entities
|
||||
│ │ │ ├── flyer.types.ts
|
||||
│ │ │ ├── user.types.ts
|
||||
│ │ │ ├── shopping.types.ts
|
||||
│ │ │ ├── recipe.types.ts
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ ├── api/ # API contract types
|
||||
│ │ │ ├── requests.ts
|
||||
│ │ │ ├── responses.ts
|
||||
│ │ │ ├── errors.ts
|
||||
│ │ │ └── index.ts
|
||||
│ │ │
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ ├── schemas/ # Zod validation schemas
|
||||
│ │ ├── flyer.schema.ts
|
||||
│ │ ├── user.schema.ts
|
||||
│ │ ├── auth.schema.ts
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ ├── constants/ # Shared constants
|
||||
│ │ ├── categories.ts
|
||||
│ │ ├── errorCodes.ts
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ └── utils/ # Isomorphic utilities
|
||||
│ ├── formatting.ts
|
||||
│ ├── validation.ts
|
||||
│ └── index.ts
|
||||
│
|
||||
├── tests/ # Test infrastructure
|
||||
│ ├── setup/
|
||||
│ │ ├── vitest.setup.ts
|
||||
│ │ └── testDb.setup.ts
|
||||
│ │
|
||||
│ ├── fixtures/
|
||||
│ │ ├── mockFactories.ts
|
||||
│ │ ├── sampleFlyers/
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ ├── utils/
|
||||
│ │ ├── testHelpers.ts
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ ├── integration/ # Integration tests
|
||||
│ │ ├── api/
|
||||
│ │ └── database/
|
||||
│ │
|
||||
│ └── e2e/ # End-to-end tests
|
||||
│ └── flows/
|
||||
│
|
||||
├── scripts/ # Build and utility scripts
|
||||
│ ├── seed.ts
|
||||
│ ├── migrate.ts
|
||||
│ └── generateTypes.ts
|
||||
│
|
||||
└── index.tsx # Client entry point
|
||||
```
|
||||
|
||||
## Domain Module Structure
|
||||
|
||||
Each server domain follows a consistent structure:
|
||||
|
||||
```
|
||||
domains/flyer/
|
||||
├── flyer.service.ts # Business logic
|
||||
├── flyer.routes.ts # Express routes
|
||||
├── flyer.controller.ts # Route handlers
|
||||
├── flyer.repository.ts # Database access
|
||||
├── flyer.types.ts # Domain-specific types
|
||||
├── flyer.service.test.ts # Service tests
|
||||
├── flyer.routes.test.ts # Route tests
|
||||
└── index.ts # Public API
|
||||
```
|
||||
|
||||
### Domain Index Pattern
|
||||
|
||||
Each domain exports a clean public API:
|
||||
|
||||
```typescript
|
||||
// server/domains/flyer/index.ts
|
||||
export { FlyerService } from './flyer.service';
|
||||
export { flyerRoutes } from './flyer.routes';
|
||||
export type { FlyerWithItems, FlyerCreateInput } from './flyer.types';
|
||||
```
|
||||
|
||||
## Client Feature Module Structure
|
||||
|
||||
Each client feature follows a consistent structure:
|
||||
|
||||
```
|
||||
client/features/flyer/
|
||||
├── components/
|
||||
│ ├── FlyerCard.tsx
|
||||
│ ├── FlyerCard.test.tsx
|
||||
│ ├── FlyerGrid.tsx
|
||||
│ └── index.ts
|
||||
├── hooks/
|
||||
│ ├── useFlyersQuery.ts
|
||||
│ ├── useFlyerUploadMutation.ts
|
||||
│ └── index.ts
|
||||
├── types.ts # Feature-specific client types
|
||||
└── index.ts # Public API
|
||||
```
|
||||
|
||||
## Import Path Aliases
|
||||
|
||||
Configure TypeScript and bundler for clean imports:
|
||||
|
||||
```typescript
|
||||
// tsconfig.json paths
|
||||
{
|
||||
"paths": {
|
||||
"@/client/*": ["src/client/*"],
|
||||
"@/server/*": ["src/server/*"],
|
||||
"@/shared/*": ["src/shared/*"],
|
||||
"@/tests/*": ["src/tests/*"]
|
||||
}
|
||||
}
|
||||
|
||||
// Usage examples
|
||||
import { Button, Card } from '@/client/components/ui';
|
||||
import { useFlyersQuery } from '@/client/features/flyer';
|
||||
import { FlyerService } from '@/server/domains/flyer';
|
||||
import type { Flyer } from '@/shared/types/entities';
|
||||
```
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
Given the scope of this reorganization, migrate incrementally:
|
||||
|
||||
### Phase 1: Create Directory Structure
|
||||
|
||||
1. Create `client/`, `server/`, `shared/` directories
|
||||
2. Set up path aliases in tsconfig.json
|
||||
3. Update build configuration (Vite)
|
||||
|
||||
### Phase 2: Migrate Shared Code
|
||||
|
||||
1. Move types to `shared/types/`
|
||||
2. Move schemas to `shared/schemas/`
|
||||
3. Move shared utils to `shared/utils/`
|
||||
4. Update imports across codebase
|
||||
|
||||
### Phase 3: Migrate Server Code
|
||||
|
||||
1. Create `server/domains/` structure
|
||||
2. Move one domain at a time (start with `auth` or `user`)
|
||||
3. Move each service + routes + repository together
|
||||
4. Update route registration in app.ts
|
||||
5. Run tests after each domain migration
|
||||
|
||||
### Phase 4: Migrate Client Code
|
||||
|
||||
1. Create `client/features/` structure
|
||||
2. Move components into features
|
||||
3. Move hooks into features or shared hooks
|
||||
4. Move pages to `client/pages/`
|
||||
5. Organize shared components into categories
|
||||
|
||||
### Phase 5: Cleanup
|
||||
|
||||
1. Remove empty old directories
|
||||
2. Update all remaining imports
|
||||
3. Update CI/CD paths if needed
|
||||
4. Update documentation
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
| Item | Convention | Example |
|
||||
| ----------------- | -------------------- | ----------------------- |
|
||||
| Domain directory | lowercase | `flyer/`, `shopping/` |
|
||||
| Feature directory | kebab-case | `voice-assistant/` |
|
||||
| Service file | domain.service.ts | `flyer.service.ts` |
|
||||
| Route file | domain.routes.ts | `flyer.routes.ts` |
|
||||
| Repository file | domain.repository.ts | `flyer.repository.ts` |
|
||||
| Component file | PascalCase.tsx | `FlyerCard.tsx` |
|
||||
| Hook file | camelCase.ts | `useFlyersQuery.ts` |
|
||||
| Type file | domain.types.ts | `flyer.types.ts` |
|
||||
| Test file | \*.test.ts(x) | `flyer.service.test.ts` |
|
||||
| Index file | index.ts | `index.ts` |
|
||||
|
||||
## File Placement Guidelines
|
||||
|
||||
**Where does this file go?**
|
||||
|
||||
| If the file is... | Place it in... |
|
||||
| ------------------------------------ | ------------------------------------------------ |
|
||||
| Used only by React | `client/` |
|
||||
| Used only by Express/Node | `server/` |
|
||||
| TypeScript types used by both | `shared/types/` |
|
||||
| Zod schemas | `shared/schemas/` |
|
||||
| React component for one feature | `client/features/{feature}/components/` |
|
||||
| React component used across features | `client/components/` |
|
||||
| React hook for one feature | `client/features/{feature}/hooks/` |
|
||||
| React hook used across features | `client/hooks/` |
|
||||
| Business logic for a domain | `server/domains/{domain}/` |
|
||||
| Database access for a domain | `server/domains/{domain}/{domain}.repository.ts` |
|
||||
| Express middleware | `server/middleware/` |
|
||||
| Background job worker | `server/infrastructure/queue/workers/` |
|
||||
| Cron job definition | `server/infrastructure/jobs/` |
|
||||
| Test factory/fixture | `tests/fixtures/` |
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- **Clear Boundaries**: Frontend, backend, and shared code are explicitly separated
|
||||
- **Feature Discoverability**: Find all code for a feature in one place
|
||||
- **Parallel Development**: Teams can work on domains independently
|
||||
- **Easier Refactoring**: Domain boundaries make changes localized
|
||||
- **Better Onboarding**: New developers navigate by feature, not file type
|
||||
- **Scalability**: Structure supports growth without becoming unwieldy
|
||||
|
||||
### Negative
|
||||
|
||||
- **Large Migration Effort**: Significant one-time cost (XL effort)
|
||||
- **Import Updates**: All imports need updating
|
||||
- **Learning Curve**: Team must learn new structure
|
||||
- **Merge Conflicts**: In-flight PRs will need rebasing
|
||||
|
||||
### Mitigation
|
||||
|
||||
- Use automated tools (e.g., `ts-morph`) to update imports
|
||||
- Migrate one domain/feature at a time
|
||||
- Create a migration checklist and track progress
|
||||
- Coordinate with team to minimize in-flight work during migration phases
|
||||
- Consider using feature flags to ship incrementally
|
||||
|
||||
## Key Differences from Current Structure
|
||||
|
||||
| Aspect | Current | Target |
|
||||
| ---------------- | -------------------------- | ----------------------------------------- |
|
||||
| Frontend/Backend | Mixed in `src/` | Separated in `client/` and `server/` |
|
||||
| Services | Flat directory (75+ files) | Grouped by domain |
|
||||
| Components | Flat directory (43+ files) | Categorized (ui, layout, feedback, forms) |
|
||||
| Types | Monolithic `types.ts` | Split by entity in `shared/types/` |
|
||||
| Features | UI-only | Full vertical slice (UI + hooks + types) |
|
||||
| Routes | Separate from services | Co-located in domain |
|
||||
| Tests | Co-located + `tests/` | Co-located + `tests/` for fixtures |
|
||||
|
||||
## Related ADRs
|
||||
|
||||
- [ADR-034](./0034-repository-pattern-standards.md) - Repository Pattern (affects domain structure)
|
||||
- [ADR-035](./0035-service-layer-architecture.md) - Service Layer (affects domain structure)
|
||||
- [ADR-044](./0044-frontend-feature-organization.md) - Frontend Features (this ADR supersedes it)
|
||||
- [ADR-045](./0045-test-data-factories-and-fixtures.md) - Test Fixtures (affects tests/ directory)
|
||||
419
docs/adr/0048-authentication-strategy.md
Normal file
419
docs/adr/0048-authentication-strategy.md
Normal file
@@ -0,0 +1,419 @@
|
||||
# ADR-048: Authentication Strategy
|
||||
|
||||
**Date**: 2026-01-09
|
||||
|
||||
**Status**: Partially Implemented
|
||||
|
||||
**Implemented**: 2026-01-09 (Local auth only)
|
||||
|
||||
## Context
|
||||
|
||||
The application requires a secure authentication system that supports both traditional email/password login and social OAuth providers (Google, GitHub). The system must handle user sessions, token refresh, account security (lockout after failed attempts), and integrate seamlessly with the existing Express middleware pipeline.
|
||||
|
||||
Currently, **only local authentication is enabled**. OAuth strategies are fully implemented but commented out, pending configuration of OAuth provider credentials.
|
||||
|
||||
## Decision
|
||||
|
||||
We will implement a stateless JWT-based authentication system with the following components:
|
||||
|
||||
1. **Local Authentication**: Email/password login with bcrypt hashing.
|
||||
2. **OAuth Authentication**: Google and GitHub OAuth 2.0 (currently disabled).
|
||||
3. **JWT Access Tokens**: Short-lived tokens (15 minutes) for API authentication.
|
||||
4. **Refresh Tokens**: Long-lived tokens (7 days) stored in HTTP-only cookies.
|
||||
5. **Account Security**: Lockout after 5 failed login attempts for 15 minutes.
|
||||
|
||||
### Design Principles
|
||||
|
||||
- **Stateless Sessions**: No server-side session storage; JWT contains all auth state.
|
||||
- **Defense in Depth**: Multiple security layers (rate limiting, lockout, secure cookies).
|
||||
- **Graceful OAuth Degradation**: OAuth is optional; system works with local auth only.
|
||||
- **OAuth User Flexibility**: OAuth users have `password_hash = NULL` in database.
|
||||
|
||||
## Current Implementation Status
|
||||
|
||||
| Component | Status | Notes |
|
||||
| ------------------------ | --------------- | ------------------------------------------------ |
|
||||
| **Local Authentication** | Enabled | Email/password with bcrypt (salt rounds = 10) |
|
||||
| **JWT Access Tokens** | Enabled | 15-minute expiry, `Authorization: Bearer` header |
|
||||
| **Refresh Tokens** | Enabled | 7-day expiry, HTTP-only cookie |
|
||||
| **Account Lockout** | Enabled | 5 failed attempts, 15-minute lockout |
|
||||
| **Password Reset** | Enabled | Email-based token flow |
|
||||
| **Google OAuth** | Disabled | Code present, commented out |
|
||||
| **GitHub OAuth** | Disabled | Code present, commented out |
|
||||
| **OAuth Routes** | Disabled | Endpoints commented out |
|
||||
| **OAuth Frontend UI** | Not Implemented | No login buttons exist |
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
```text
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ AUTHENTICATION FLOW │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ Login │───>│ Passport │───>│ JWT │───>│ Protected│ │
|
||||
│ │ Request │ │ Local │ │ Token │ │ Routes │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||||
│ │ │ │ │
|
||||
│ │ ┌──────────┐ │ │ │
|
||||
│ └────────>│ OAuth │─────────────┘ │ │
|
||||
│ (disabled) │ Provider │ │ │
|
||||
│ └──────────┘ │ │
|
||||
│ │ │
|
||||
│ ┌──────────┐ ┌──────────┐ │ │
|
||||
│ │ Refresh │───>│ New │<─────────────────────────┘ │
|
||||
│ │ Token │ │ JWT │ (when access token expires) │
|
||||
│ └──────────┘ └──────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Local Strategy (Enabled)
|
||||
|
||||
Located in `src/routes/passport.routes.ts`:
|
||||
|
||||
```typescript
|
||||
passport.use(
|
||||
new LocalStrategy(
|
||||
{ usernameField: 'email', passReqToCallback: true },
|
||||
async (req, email, password, done) => {
|
||||
// 1. Find user with profile by email
|
||||
const userprofile = await db.userRepo.findUserWithProfileByEmail(email, req.log);
|
||||
|
||||
// 2. Check account lockout
|
||||
if (userprofile.failed_login_attempts >= MAX_FAILED_ATTEMPTS) {
|
||||
// Check if lockout period has passed
|
||||
}
|
||||
|
||||
// 3. Verify password with bcrypt
|
||||
const isMatch = await bcrypt.compare(password, userprofile.password_hash);
|
||||
|
||||
// 4. On success, reset failed attempts and return user
|
||||
// 5. On failure, increment failed attempts
|
||||
},
|
||||
),
|
||||
);
|
||||
```
|
||||
|
||||
**Security Features**:
|
||||
|
||||
- Bcrypt password hashing with salt rounds = 10
|
||||
- Account lockout after 5 failed attempts
|
||||
- 15-minute lockout duration
|
||||
- Failed attempt tracking persists across lockout refreshes
|
||||
- Activity logging for failed login attempts
|
||||
|
||||
### JWT Strategy (Enabled)
|
||||
|
||||
```typescript
|
||||
const jwtOptions = {
|
||||
jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
|
||||
secretOrKey: JWT_SECRET,
|
||||
};
|
||||
|
||||
passport.use(
|
||||
new JwtStrategy(jwtOptions, async (jwt_payload, done) => {
|
||||
const userProfile = await db.userRepo.findUserProfileById(jwt_payload.user_id);
|
||||
if (userProfile) {
|
||||
return done(null, userProfile);
|
||||
}
|
||||
return done(null, false);
|
||||
}),
|
||||
);
|
||||
```
|
||||
|
||||
**Token Configuration**:
|
||||
|
||||
- Access token: 15 minutes expiry
|
||||
- Refresh token: 7 days expiry, 64-byte random hex
|
||||
- Refresh token stored in HTTP-only cookie with `secure` flag in production
|
||||
|
||||
### OAuth Strategies (Disabled)
|
||||
|
||||
#### Google OAuth
|
||||
|
||||
Located in `src/routes/passport.routes.ts` (lines 167-217, commented):
|
||||
|
||||
```typescript
|
||||
// passport.use(new GoogleStrategy({
|
||||
// clientID: process.env.GOOGLE_CLIENT_ID!,
|
||||
// clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
|
||||
// callbackURL: '/api/auth/google/callback',
|
||||
// scope: ['profile', 'email']
|
||||
// },
|
||||
// async (accessToken, refreshToken, profile, done) => {
|
||||
// const email = profile.emails?.[0]?.value;
|
||||
// const user = await db.findUserByEmail(email);
|
||||
// if (user) {
|
||||
// return done(null, user);
|
||||
// }
|
||||
// // Create new user with null password_hash
|
||||
// const newUser = await db.createUser(email, null, {
|
||||
// full_name: profile.displayName,
|
||||
// avatar_url: profile.photos?.[0]?.value
|
||||
// });
|
||||
// return done(null, newUser);
|
||||
// }
|
||||
// ));
|
||||
```
|
||||
|
||||
#### GitHub OAuth
|
||||
|
||||
Located in `src/routes/passport.routes.ts` (lines 219-269, commented):
|
||||
|
||||
```typescript
|
||||
// passport.use(new GitHubStrategy({
|
||||
// clientID: process.env.GITHUB_CLIENT_ID!,
|
||||
// clientSecret: process.env.GITHUB_CLIENT_SECRET!,
|
||||
// callbackURL: '/api/auth/github/callback',
|
||||
// scope: ['user:email']
|
||||
// },
|
||||
// async (accessToken, refreshToken, profile, done) => {
|
||||
// const email = profile.emails?.[0]?.value;
|
||||
// // Similar flow to Google OAuth
|
||||
// }
|
||||
// ));
|
||||
```
|
||||
|
||||
#### OAuth Routes (Disabled)
|
||||
|
||||
Located in `src/routes/auth.routes.ts` (lines 289-315, commented):
|
||||
|
||||
```typescript
|
||||
// const handleOAuthCallback = (req, res) => {
|
||||
// const user = req.user;
|
||||
// const accessToken = jwt.sign(payload, JWT_SECRET, { expiresIn: '15m' });
|
||||
// const refreshToken = crypto.randomBytes(64).toString('hex');
|
||||
//
|
||||
// await db.saveRefreshToken(user.user_id, refreshToken);
|
||||
// res.cookie('refreshToken', refreshToken, { httpOnly: true, secure: true });
|
||||
// res.redirect(`${FRONTEND_URL}/auth/callback?token=${accessToken}`);
|
||||
// };
|
||||
|
||||
// router.get('/google', passport.authenticate('google', { session: false }));
|
||||
// router.get('/google/callback', passport.authenticate('google', { ... }), handleOAuthCallback);
|
||||
// router.get('/github', passport.authenticate('github', { session: false }));
|
||||
// router.get('/github/callback', passport.authenticate('github', { ... }), handleOAuthCallback);
|
||||
```
|
||||
|
||||
### Database Schema
|
||||
|
||||
**Users Table** (`sql/initial_schema.sql`):
|
||||
|
||||
```sql
|
||||
CREATE TABLE public.users (
|
||||
user_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||
email TEXT NOT NULL UNIQUE,
|
||||
password_hash TEXT, -- NULL for OAuth-only users
|
||||
refresh_token TEXT, -- Current refresh token
|
||||
failed_login_attempts INTEGER DEFAULT 0,
|
||||
last_failed_login TIMESTAMPTZ,
|
||||
created_at TIMESTAMPTZ DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ DEFAULT now()
|
||||
);
|
||||
```
|
||||
|
||||
**Note**: There is no separate OAuth provider mapping table. OAuth users are identified by `password_hash = NULL`. If a user signs up via OAuth and later wants to add a password, this would require schema changes.
|
||||
|
||||
### Authentication Middleware
|
||||
|
||||
Located in `src/routes/passport.routes.ts`:
|
||||
|
||||
```typescript
|
||||
// Require admin role
|
||||
export const isAdmin = (req, res, next) => {
|
||||
if (req.user?.role === 'admin') {
|
||||
next();
|
||||
} else {
|
||||
next(new ForbiddenError('Administrator access required.'));
|
||||
}
|
||||
};
|
||||
|
||||
// Optional auth - attach user if present, continue if not
|
||||
export const optionalAuth = (req, res, next) => {
|
||||
passport.authenticate('jwt', { session: false }, (err, user) => {
|
||||
if (user) req.user = user;
|
||||
next();
|
||||
})(req, res, next);
|
||||
};
|
||||
|
||||
// Mock auth for testing (only in NODE_ENV=test)
|
||||
export const mockAuth = (req, res, next) => {
|
||||
if (process.env.NODE_ENV === 'test') {
|
||||
req.user = createMockUserProfile({ role: 'admin' });
|
||||
}
|
||||
next();
|
||||
};
|
||||
```
|
||||
|
||||
## Enabling OAuth
|
||||
|
||||
### Step 1: Set Environment Variables
|
||||
|
||||
Add to `.env`:
|
||||
|
||||
```bash
|
||||
# Google OAuth
|
||||
GOOGLE_CLIENT_ID=your-google-client-id
|
||||
GOOGLE_CLIENT_SECRET=your-google-client-secret
|
||||
|
||||
# GitHub OAuth
|
||||
GITHUB_CLIENT_ID=your-github-client-id
|
||||
GITHUB_CLIENT_SECRET=your-github-client-secret
|
||||
```
|
||||
|
||||
### Step 2: Configure OAuth Providers
|
||||
|
||||
**Google Cloud Console**:
|
||||
|
||||
1. Create project at <https://console.cloud.google.com/>
|
||||
2. Enable Google+ API
|
||||
3. Create OAuth 2.0 credentials (Web Application)
|
||||
4. Add authorized redirect URI:
|
||||
- Development: `http://localhost:3001/api/auth/google/callback`
|
||||
- Production: `https://your-domain.com/api/auth/google/callback`
|
||||
|
||||
**GitHub Developer Settings**:
|
||||
|
||||
1. Go to <https://github.com/settings/developers>
|
||||
2. Create new OAuth App
|
||||
3. Set Authorization callback URL:
|
||||
- Development: `http://localhost:3001/api/auth/github/callback`
|
||||
- Production: `https://your-domain.com/api/auth/github/callback`
|
||||
|
||||
### Step 3: Uncomment Backend Code
|
||||
|
||||
**In `src/routes/passport.routes.ts`**:
|
||||
|
||||
1. Uncomment import statements (lines 5-6):
|
||||
|
||||
```typescript
|
||||
import { Strategy as GoogleStrategy } from 'passport-google-oauth20';
|
||||
import { Strategy as GitHubStrategy } from 'passport-github2';
|
||||
```
|
||||
|
||||
2. Uncomment Google strategy (lines 167-217)
|
||||
3. Uncomment GitHub strategy (lines 219-269)
|
||||
|
||||
**In `src/routes/auth.routes.ts`**:
|
||||
|
||||
1. Uncomment `handleOAuthCallback` function (lines 291-309)
|
||||
2. Uncomment OAuth routes (lines 311-315)
|
||||
|
||||
### Step 4: Add Frontend OAuth Buttons
|
||||
|
||||
Create login buttons that redirect to:
|
||||
|
||||
- Google: `GET /api/auth/google`
|
||||
- GitHub: `GET /api/auth/github`
|
||||
|
||||
Handle callback at `/auth/callback?token=<accessToken>`:
|
||||
|
||||
1. Extract token from URL
|
||||
2. Store in client-side token storage
|
||||
3. Redirect to dashboard
|
||||
|
||||
### Step 5: Handle OAuth Callback Page
|
||||
|
||||
Create `src/pages/AuthCallback.tsx`:
|
||||
|
||||
```typescript
|
||||
const AuthCallback = () => {
|
||||
const token = new URLSearchParams(location.search).get('token');
|
||||
if (token) {
|
||||
setToken(token);
|
||||
navigate('/dashboard');
|
||||
} else {
|
||||
navigate('/login?error=auth_failed');
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## Known Limitations
|
||||
|
||||
1. **No OAuth Provider ID Mapping**: Users are identified by email only. If a user has accounts with different emails on Google and GitHub, they create separate accounts.
|
||||
|
||||
2. **No Account Linking**: Users cannot link multiple OAuth providers to one account.
|
||||
|
||||
3. **No Password Addition for OAuth Users**: OAuth-only users cannot add a password to enable local login.
|
||||
|
||||
4. **No PKCE Flow**: OAuth implementation uses standard flow, not PKCE (Proof Key for Code Exchange).
|
||||
|
||||
5. **No OAuth State Parameter Validation**: The commented code doesn't show explicit state parameter handling for CSRF protection (Passport may handle this internally).
|
||||
|
||||
6. **No Refresh Token from OAuth Providers**: Only email/profile data is extracted; OAuth refresh tokens are not stored for API access.
|
||||
|
||||
## Dependencies
|
||||
|
||||
**Installed** (all available):
|
||||
|
||||
- `passport` v0.7.0
|
||||
- `passport-local` v1.0.0
|
||||
- `passport-jwt` v4.0.1
|
||||
- `passport-google-oauth20` v2.0.0
|
||||
- `passport-github2` v0.1.12
|
||||
- `bcrypt` v5.x
|
||||
- `jsonwebtoken` v9.x
|
||||
|
||||
**Type Definitions**:
|
||||
|
||||
- `@types/passport`
|
||||
- `@types/passport-local`
|
||||
- `@types/passport-jwt`
|
||||
- `@types/passport-google-oauth20`
|
||||
- `@types/passport-github2`
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- **Stateless Architecture**: No session storage required; scales horizontally.
|
||||
- **Secure by Default**: HTTP-only cookies, short token expiry, bcrypt hashing.
|
||||
- **Account Protection**: Lockout prevents brute-force attacks.
|
||||
- **Flexible OAuth**: Can enable/disable OAuth without code changes (just env vars + uncommenting).
|
||||
- **Graceful Degradation**: System works with local auth only.
|
||||
|
||||
### Negative
|
||||
|
||||
- **OAuth Disabled by Default**: Requires manual uncommenting to enable.
|
||||
- **No Account Linking**: Multiple OAuth providers create separate accounts.
|
||||
- **Frontend Work Required**: OAuth login buttons don't exist yet.
|
||||
- **Token in URL**: OAuth callback passes token in URL (visible in browser history).
|
||||
|
||||
### Mitigation
|
||||
|
||||
- Document OAuth enablement steps clearly (see AUTHENTICATION.md).
|
||||
- Consider adding OAuth provider ID columns for future account linking.
|
||||
- Use URL fragment (`#token=`) instead of query parameter for callback.
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
| ------------------------------- | ------------------------------------------------ |
|
||||
| `src/routes/passport.routes.ts` | Passport strategies (local, JWT, OAuth) |
|
||||
| `src/routes/auth.routes.ts` | Auth endpoints (login, register, refresh, OAuth) |
|
||||
| `src/services/authService.ts` | Auth business logic |
|
||||
| `src/services/db/user.db.ts` | User database operations |
|
||||
| `src/config/env.ts` | Environment variable validation |
|
||||
| `AUTHENTICATION.md` | OAuth setup guide |
|
||||
| `.env.example` | Environment variable template |
|
||||
|
||||
## Related ADRs
|
||||
|
||||
- [ADR-011](./0011-advanced-authorization-and-access-control-strategy.md) - Authorization and Access Control
|
||||
- [ADR-016](./0016-api-security-hardening.md) - API Security (rate limiting, headers)
|
||||
- [ADR-032](./0032-rate-limiting-strategy.md) - Rate Limiting
|
||||
- [ADR-043](./0043-express-middleware-pipeline.md) - Middleware Pipeline
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
1. **Enable OAuth**: Uncomment strategies and configure providers.
|
||||
2. **Add OAuth Provider Mapping Table**: Store `googleId`, `githubId` for account linking.
|
||||
3. **Implement Account Linking**: Allow users to connect multiple OAuth providers.
|
||||
4. **Add Password to OAuth Users**: Allow OAuth users to set a password.
|
||||
5. **Implement PKCE**: Add PKCE flow for enhanced OAuth security.
|
||||
6. **Token in Fragment**: Use URL fragment for OAuth callback token.
|
||||
7. **OAuth Token Storage**: Store OAuth refresh tokens for provider API access.
|
||||
8. **Magic Link Login**: Add passwordless email login option.
|
||||
@@ -15,9 +15,9 @@ This document tracks the implementation status and estimated effort for all Arch
|
||||
|
||||
| Status | Count |
|
||||
| ---------------------------- | ----- |
|
||||
| Accepted (Fully Implemented) | 22 |
|
||||
| Accepted (Fully Implemented) | 28 |
|
||||
| Partially Implemented | 2 |
|
||||
| Proposed (Not Started) | 15 |
|
||||
| Proposed (Not Started) | 16 |
|
||||
|
||||
---
|
||||
|
||||
@@ -83,29 +83,36 @@ This document tracks the implementation status and estimated effort for all Arch
|
||||
|
||||
### Category 7: Frontend / User Interface
|
||||
|
||||
| ADR | Title | Status | Effort | Notes |
|
||||
| ------------------------------------------------------------------------ | ------------------- | -------- | ------ | ------------------------------------------- |
|
||||
| [ADR-005](./0005-frontend-state-management-and-server-cache-strategy.md) | State Management | Accepted | - | Fully implemented |
|
||||
| [ADR-012](./0012-frontend-component-library-and-design-system.md) | Component Library | Partial | L | Core components done, design tokens pending |
|
||||
| [ADR-025](./0025-internationalization-and-localization-strategy.md) | i18n & l10n | Proposed | XL | All UI strings need extraction |
|
||||
| [ADR-026](./0026-standardized-client-side-structured-logging.md) | Client-Side Logging | Accepted | - | Fully implemented |
|
||||
| ADR | Title | Status | Effort | Notes |
|
||||
| ------------------------------------------------------------------------ | -------------------- | -------- | ------ | ------------------------------------------- |
|
||||
| [ADR-005](./0005-frontend-state-management-and-server-cache-strategy.md) | State Management | Accepted | - | Fully implemented |
|
||||
| [ADR-012](./0012-frontend-component-library-and-design-system.md) | Component Library | Partial | L | Core components done, design tokens pending |
|
||||
| [ADR-025](./0025-internationalization-and-localization-strategy.md) | i18n & l10n | Proposed | XL | All UI strings need extraction |
|
||||
| [ADR-026](./0026-standardized-client-side-structured-logging.md) | Client-Side Logging | Accepted | - | Fully implemented |
|
||||
| [ADR-044](./0044-frontend-feature-organization.md) | Feature Organization | Accepted | - | Fully implemented |
|
||||
|
||||
### Category 8: Development Workflow & Quality
|
||||
|
||||
| ADR | Title | Status | Effort | Notes |
|
||||
| ----------------------------------------------------------------------------- | -------------------- | -------- | ------ | ----------------- |
|
||||
| [ADR-010](./0010-testing-strategy-and-standards.md) | Testing Strategy | Accepted | - | Fully implemented |
|
||||
| [ADR-021](./0021-code-formatting-and-linting-unification.md) | Formatting & Linting | Accepted | - | Fully implemented |
|
||||
| [ADR-027](./0027-standardized-naming-convention-for-ai-and-database-types.md) | Naming Conventions | Accepted | - | Fully implemented |
|
||||
| ADR | Title | Status | Effort | Notes |
|
||||
| ----------------------------------------------------------------------------- | -------------------- | -------- | ------ | -------------------- |
|
||||
| [ADR-010](./0010-testing-strategy-and-standards.md) | Testing Strategy | Accepted | - | Fully implemented |
|
||||
| [ADR-021](./0021-code-formatting-and-linting-unification.md) | Formatting & Linting | Accepted | - | Fully implemented |
|
||||
| [ADR-027](./0027-standardized-naming-convention-for-ai-and-database-types.md) | Naming Conventions | Accepted | - | Fully implemented |
|
||||
| [ADR-045](./0045-test-data-factories-and-fixtures.md) | Test Data Factories | Accepted | - | Fully implemented |
|
||||
| [ADR-047](./0047-project-file-and-folder-organization.md) | Project Organization | Proposed | XL | Major reorganization |
|
||||
|
||||
### Category 9: Architecture Patterns
|
||||
|
||||
| ADR | Title | Status | Effort | Notes |
|
||||
| -------------------------------------------------- | -------------------- | -------- | ------ | ----------------- |
|
||||
| [ADR-034](./0034-repository-pattern-standards.md) | Repository Pattern | Accepted | - | Fully implemented |
|
||||
| [ADR-035](./0035-service-layer-architecture.md) | Service Layer | Accepted | - | Fully implemented |
|
||||
| [ADR-036](./0036-event-bus-and-pub-sub-pattern.md) | Event Bus | Accepted | - | Fully implemented |
|
||||
| [ADR-039](./0039-dependency-injection-pattern.md) | Dependency Injection | Accepted | - | Fully implemented |
|
||||
| ADR | Title | Status | Effort | Notes |
|
||||
| -------------------------------------------------------- | --------------------- | -------- | ------ | ----------------- |
|
||||
| [ADR-034](./0034-repository-pattern-standards.md) | Repository Pattern | Accepted | - | Fully implemented |
|
||||
| [ADR-035](./0035-service-layer-architecture.md) | Service Layer | Accepted | - | Fully implemented |
|
||||
| [ADR-036](./0036-event-bus-and-pub-sub-pattern.md) | Event Bus | Accepted | - | Fully implemented |
|
||||
| [ADR-039](./0039-dependency-injection-pattern.md) | Dependency Injection | Accepted | - | Fully implemented |
|
||||
| [ADR-041](./0041-ai-gemini-integration-architecture.md) | AI/Gemini Integration | Accepted | - | Fully implemented |
|
||||
| [ADR-042](./0042-email-and-notification-architecture.md) | Email & Notifications | Accepted | - | Fully implemented |
|
||||
| [ADR-043](./0043-express-middleware-pipeline.md) | Middleware Pipeline | Accepted | - | Fully implemented |
|
||||
| [ADR-046](./0046-image-processing-pipeline.md) | Image Processing | Accepted | - | Fully implemented |
|
||||
|
||||
---
|
||||
|
||||
@@ -133,6 +140,13 @@ These ADRs are proposed but not yet implemented, ordered by suggested implementa
|
||||
|
||||
| Date | ADR | Change |
|
||||
| ---------- | ------- | --------------------------------------------------------------------------------------------- |
|
||||
| 2026-01-09 | ADR-047 | Created - Documents target project file/folder organization with migration plan |
|
||||
| 2026-01-09 | ADR-041 | Created - Documents AI/Gemini integration with model fallback and rate limiting |
|
||||
| 2026-01-09 | ADR-042 | Created - Documents email and notification architecture with BullMQ queuing |
|
||||
| 2026-01-09 | ADR-043 | Created - Documents Express middleware pipeline ordering and patterns |
|
||||
| 2026-01-09 | ADR-044 | Created - Documents frontend feature-based folder organization |
|
||||
| 2026-01-09 | ADR-045 | Created - Documents test data factory pattern for mock generation |
|
||||
| 2026-01-09 | ADR-046 | Created - Documents image processing pipeline with Sharp and EXIF stripping |
|
||||
| 2026-01-09 | ADR-026 | Fully implemented - all client-side components, hooks, and services now use structured logger |
|
||||
| 2026-01-09 | ADR-028 | Fully implemented - all routes, middleware, and tests updated |
|
||||
|
||||
|
||||
@@ -33,6 +33,7 @@ This directory contains a log of the architectural decisions made for the Flyer
|
||||
**[ADR-029](./0029-secret-rotation-and-key-management.md)**: Secret Rotation and Key Management Strategy (Proposed)
|
||||
**[ADR-032](./0032-rate-limiting-strategy.md)**: Rate Limiting Strategy (Accepted)
|
||||
**[ADR-033](./0033-file-upload-and-storage-strategy.md)**: File Upload and Storage Strategy (Accepted)
|
||||
**[ADR-048](./0048-authentication-strategy.md)**: Authentication Strategy (Partially Implemented)
|
||||
|
||||
## 5. Observability & Monitoring
|
||||
|
||||
@@ -54,6 +55,7 @@ This directory contains a log of the architectural decisions made for the Flyer
|
||||
**[ADR-012](./0012-frontend-component-library-and-design-system.md)**: Frontend Component Library and Design System (Partially Implemented)
|
||||
**[ADR-025](./0025-internationalization-and-localization-strategy.md)**: Internationalization (i18n) and Localization (l10n) Strategy (Proposed)
|
||||
**[ADR-026](./0026-standardized-client-side-structured-logging.md)**: Standardized Client-Side Structured Logging (Proposed)
|
||||
**[ADR-044](./0044-frontend-feature-organization.md)**: Frontend Feature Organization Pattern (Accepted)
|
||||
|
||||
## 8. Development Workflow & Quality
|
||||
|
||||
@@ -61,6 +63,8 @@ This directory contains a log of the architectural decisions made for the Flyer
|
||||
**[ADR-021](./0021-code-formatting-and-linting-unification.md)**: Code Formatting and Linting Unification (Accepted)
|
||||
**[ADR-027](./0027-standardized-naming-convention-for-ai-and-database-types.md)**: Standardized Naming Convention for AI and Database Types (Accepted)
|
||||
**[ADR-040](./0040-testing-economics-and-priorities.md)**: Testing Economics and Priorities (Accepted)
|
||||
**[ADR-045](./0045-test-data-factories-and-fixtures.md)**: Test Data Factories and Fixtures (Accepted)
|
||||
**[ADR-047](./0047-project-file-and-folder-organization.md)**: Project File and Folder Organization (Proposed)
|
||||
|
||||
## 9. Architecture Patterns
|
||||
|
||||
@@ -68,3 +72,7 @@ This directory contains a log of the architectural decisions made for the Flyer
|
||||
**[ADR-035](./0035-service-layer-architecture.md)**: Service Layer Architecture (Accepted)
|
||||
**[ADR-036](./0036-event-bus-and-pub-sub-pattern.md)**: Event Bus and Pub/Sub Pattern (Accepted)
|
||||
**[ADR-039](./0039-dependency-injection-pattern.md)**: Dependency Injection Pattern (Accepted)
|
||||
**[ADR-041](./0041-ai-gemini-integration-architecture.md)**: AI/Gemini Integration Architecture (Accepted)
|
||||
**[ADR-042](./0042-email-and-notification-architecture.md)**: Email and Notification Architecture (Accepted)
|
||||
**[ADR-043](./0043-express-middleware-pipeline.md)**: Express Middleware Pipeline Architecture (Accepted)
|
||||
**[ADR-046](./0046-image-processing-pipeline.md)**: Image Processing Pipeline (Accepted)
|
||||
|
||||
@@ -22,7 +22,9 @@ describe('ConfirmationModal (in components)', () => {
|
||||
});
|
||||
|
||||
it('should not render when isOpen is false', () => {
|
||||
const { container } = renderWithProviders(<ConfirmationModal {...defaultProps} isOpen={false} />);
|
||||
const { container } = renderWithProviders(
|
||||
<ConfirmationModal {...defaultProps} isOpen={false} />,
|
||||
);
|
||||
expect(container.firstChild).toBeNull();
|
||||
});
|
||||
|
||||
|
||||
@@ -11,7 +11,10 @@ vi.mock('zxcvbn');
|
||||
|
||||
describe('PasswordStrengthIndicator', () => {
|
||||
it('should render 5 gray bars when no password is provided', () => {
|
||||
(zxcvbn as Mock).mockReturnValue({ score: -1, feedback: { warning: '', suggestions: [] } });
|
||||
(zxcvbn as Mock).mockReturnValue({
|
||||
score: -1,
|
||||
feedback: { warning: '', suggestions: [] },
|
||||
});
|
||||
const { container } = renderWithProviders(<PasswordStrengthIndicator password="" />);
|
||||
const bars = container.querySelectorAll('.h-1\\.5');
|
||||
expect(bars).toHaveLength(5);
|
||||
@@ -28,8 +31,13 @@ describe('PasswordStrengthIndicator', () => {
|
||||
{ score: 3, label: 'Good', color: 'bg-yellow-500', bars: 4 },
|
||||
{ score: 4, label: 'Strong', color: 'bg-green-500', bars: 5 },
|
||||
])('should render correctly for score $score ($label)', ({ score, label, color, bars }) => {
|
||||
(zxcvbn as Mock).mockReturnValue({ score, feedback: { warning: '', suggestions: [] } });
|
||||
const { container } = renderWithProviders(<PasswordStrengthIndicator password="some-password" />);
|
||||
(zxcvbn as Mock).mockReturnValue({
|
||||
score,
|
||||
feedback: { warning: '', suggestions: [] },
|
||||
});
|
||||
const { container } = renderWithProviders(
|
||||
<PasswordStrengthIndicator password="some-password" />,
|
||||
);
|
||||
|
||||
// Check the label
|
||||
expect(screen.getByText(label)).toBeInTheDocument();
|
||||
@@ -82,7 +90,10 @@ describe('PasswordStrengthIndicator', () => {
|
||||
});
|
||||
|
||||
it('should use default empty string if password prop is undefined', () => {
|
||||
(zxcvbn as Mock).mockReturnValue({ score: 0, feedback: { warning: '', suggestions: [] } });
|
||||
(zxcvbn as Mock).mockReturnValue({
|
||||
score: 0,
|
||||
feedback: { warning: '', suggestions: [] },
|
||||
});
|
||||
const { container } = renderWithProviders(<PasswordStrengthIndicator />);
|
||||
const bars = container.querySelectorAll('.h-1\\.5');
|
||||
expect(bars).toHaveLength(5);
|
||||
@@ -94,7 +105,10 @@ describe('PasswordStrengthIndicator', () => {
|
||||
|
||||
it('should handle out-of-range scores gracefully (defensive)', () => {
|
||||
// Mock a score that isn't 0-4 to hit default switch cases
|
||||
(zxcvbn as Mock).mockReturnValue({ score: 99, feedback: { warning: '', suggestions: [] } });
|
||||
(zxcvbn as Mock).mockReturnValue({
|
||||
score: 99,
|
||||
feedback: { warning: '', suggestions: [] },
|
||||
});
|
||||
const { container } = renderWithProviders(<PasswordStrengthIndicator password="test" />);
|
||||
|
||||
// Check bars - should hit default case in getBarColor which returns gray
|
||||
|
||||
@@ -54,7 +54,10 @@ describe('RecipeSuggester Component', () => {
|
||||
// Add a delay to ensure the loading state is visible during the test
|
||||
mockedApiClient.suggestRecipe.mockImplementation(async () => {
|
||||
await new Promise((resolve) => setTimeout(resolve, 50));
|
||||
return { ok: true, json: async () => ({ suggestion: mockSuggestion }) } as Response;
|
||||
return {
|
||||
ok: true,
|
||||
json: async () => ({ suggestion: mockSuggestion }),
|
||||
} as Response;
|
||||
});
|
||||
|
||||
const button = screen.getByRole('button', { name: /Suggest a Recipe/i });
|
||||
@@ -120,7 +123,7 @@ describe('RecipeSuggester Component', () => {
|
||||
|
||||
expect(logger.error).toHaveBeenCalledWith(
|
||||
{ error: networkError },
|
||||
'Failed to fetch recipe suggestion.'
|
||||
'Failed to fetch recipe suggestion.',
|
||||
);
|
||||
console.log('TEST: Network error caught and logged');
|
||||
});
|
||||
@@ -196,7 +199,7 @@ describe('RecipeSuggester Component', () => {
|
||||
|
||||
expect(logger.error).toHaveBeenCalledWith(
|
||||
{ error: 'Something weird happened' },
|
||||
'Failed to fetch recipe suggestion.'
|
||||
'Failed to fetch recipe suggestion.',
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -9,45 +9,60 @@ export const RecipeSuggester: React.FC = () => {
|
||||
const [isLoading, setIsLoading] = useState<boolean>(false);
|
||||
const [error, setError] = useState<string | null>(null);
|
||||
|
||||
const handleSubmit = useCallback(async (event: React.FormEvent<HTMLFormElement>) => {
|
||||
event.preventDefault();
|
||||
setIsLoading(true);
|
||||
setError(null);
|
||||
setSuggestion(null);
|
||||
const handleSubmit = useCallback(
|
||||
async (event: React.FormEvent<HTMLFormElement>) => {
|
||||
event.preventDefault();
|
||||
setIsLoading(true);
|
||||
setError(null);
|
||||
setSuggestion(null);
|
||||
|
||||
const ingredientList = ingredients.split(',').map(item => item.trim()).filter(Boolean);
|
||||
const ingredientList = ingredients
|
||||
.split(',')
|
||||
.map((item) => item.trim())
|
||||
.filter(Boolean);
|
||||
|
||||
if (ingredientList.length === 0) {
|
||||
setError('Please enter at least one ingredient.');
|
||||
setIsLoading(false);
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
const response = await suggestRecipe(ingredientList);
|
||||
const data = await response.json();
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error(data.message || 'Failed to get suggestion.');
|
||||
if (ingredientList.length === 0) {
|
||||
setError('Please enter at least one ingredient.');
|
||||
setIsLoading(false);
|
||||
return;
|
||||
}
|
||||
|
||||
setSuggestion(data.suggestion);
|
||||
} catch (err) {
|
||||
const errorMessage = err instanceof Error ? err.message : 'An unknown error occurred.';
|
||||
logger.error({ error: err }, 'Failed to fetch recipe suggestion.');
|
||||
setError(errorMessage);
|
||||
} finally {
|
||||
setIsLoading(false);
|
||||
}
|
||||
}, [ingredients]);
|
||||
try {
|
||||
const response = await suggestRecipe(ingredientList);
|
||||
const data = await response.json();
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error(data.message || 'Failed to get suggestion.');
|
||||
}
|
||||
|
||||
setSuggestion(data.suggestion);
|
||||
} catch (err) {
|
||||
const errorMessage = err instanceof Error ? err.message : 'An unknown error occurred.';
|
||||
logger.error({ error: err }, 'Failed to fetch recipe suggestion.');
|
||||
setError(errorMessage);
|
||||
} finally {
|
||||
setIsLoading(false);
|
||||
}
|
||||
},
|
||||
[ingredients],
|
||||
);
|
||||
|
||||
return (
|
||||
<div className="bg-white dark:bg-gray-800 shadow rounded-lg p-6">
|
||||
<h2 className="text-xl font-semibold text-gray-900 dark:text-white mb-2">Get a Recipe Suggestion</h2>
|
||||
<p className="text-gray-600 dark:text-gray-400 mb-4">Enter some ingredients you have, separated by commas.</p>
|
||||
<h2 className="text-xl font-semibold text-gray-900 dark:text-white mb-2">
|
||||
Get a Recipe Suggestion
|
||||
</h2>
|
||||
<p className="text-gray-600 dark:text-gray-400 mb-4">
|
||||
Enter some ingredients you have, separated by commas.
|
||||
</p>
|
||||
<form onSubmit={handleSubmit}>
|
||||
<div className="mb-4">
|
||||
<label htmlFor="ingredients-input" className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">Ingredients:</label>
|
||||
<label
|
||||
htmlFor="ingredients-input"
|
||||
className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1"
|
||||
>
|
||||
Ingredients:
|
||||
</label>
|
||||
<input
|
||||
id="ingredients-input"
|
||||
type="text"
|
||||
@@ -58,19 +73,27 @@ export const RecipeSuggester: React.FC = () => {
|
||||
className="block w-full rounded-md border-gray-300 shadow-sm focus:border-blue-500 focus:ring-blue-500 dark:bg-gray-700 dark:border-gray-600 dark:text-white sm:text-sm p-2 border"
|
||||
/>
|
||||
</div>
|
||||
<button type="submit" disabled={isLoading} className="w-full flex justify-center py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 disabled:opacity-50 transition-colors">
|
||||
<button
|
||||
type="submit"
|
||||
disabled={isLoading}
|
||||
className="w-full flex justify-center py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 disabled:opacity-50 transition-colors"
|
||||
>
|
||||
{isLoading ? 'Getting suggestion...' : 'Suggest a Recipe'}
|
||||
</button>
|
||||
</form>
|
||||
|
||||
{error && (
|
||||
<div className="mt-4 p-4 bg-red-50 dark:bg-red-900/50 text-red-700 dark:text-red-200 rounded-md text-sm">{error}</div>
|
||||
<div className="mt-4 p-4 bg-red-50 dark:bg-red-900/50 text-red-700 dark:text-red-200 rounded-md text-sm">
|
||||
{error}
|
||||
</div>
|
||||
)}
|
||||
|
||||
{suggestion && (
|
||||
<div className="mt-6 bg-gray-50 dark:bg-gray-700/50 rounded-lg p-4 border border-gray-200 dark:border-gray-600">
|
||||
<div className="prose dark:prose-invert max-w-none">
|
||||
<h5 className="text-lg font-medium text-gray-900 dark:text-white mb-2">Recipe Suggestion</h5>
|
||||
<h5 className="text-lg font-medium text-gray-900 dark:text-white mb-2">
|
||||
Recipe Suggestion
|
||||
</h5>
|
||||
<p className="text-gray-700 dark:text-gray-300 whitespace-pre-wrap">{suggestion}</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@@ -19,7 +19,9 @@ export const StatCard: React.FC<StatCardProps> = ({ title, value, icon }) => {
|
||||
</div>
|
||||
<div className="ml-5 w-0 flex-1">
|
||||
<dl>
|
||||
<dt className="text-sm font-medium text-gray-500 dark:text-gray-400 truncate">{title}</dt>
|
||||
<dt className="text-sm font-medium text-gray-500 dark:text-gray-400 truncate">
|
||||
{title}
|
||||
</dt>
|
||||
<dd>
|
||||
<div className="text-lg font-medium text-gray-900 dark:text-white">{value}</div>
|
||||
</dd>
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
// src/hooks/queries/useFlyerItemsQuery.test.tsx
|
||||
import { renderHook, waitFor } from '@testing-library/react';
|
||||
import { renderHook, waitFor, act } from '@testing-library/react';
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
|
||||
import type { ReactNode } from 'react';
|
||||
@@ -103,7 +103,9 @@ describe('useFlyerItemsQuery', () => {
|
||||
const { result } = renderHook(() => useFlyerItemsQuery(undefined), { wrapper });
|
||||
|
||||
// Force the query to run by calling refetch
|
||||
await result.current.refetch();
|
||||
await act(async () => {
|
||||
await result.current.refetch();
|
||||
});
|
||||
|
||||
await waitFor(() => expect(result.current.isError).toBe(true));
|
||||
|
||||
|
||||
Reference in New Issue
Block a user