Tanya 845b3f3b87 docs: Update architecture documentation and add auto-match load analysis

This commit updates the `ARCHITECTURE.md` file to reflect the transition to a web-based application, including new features and system overview. Additionally, it introduces `AUTOMATCH_LOAD_ANALYSIS.md`, detailing performance issues with the Auto-Match page and recommendations for optimizations. A new document, `CONFIDENCE_CALIBRATION_SUMMARY.md`, is also added to explain the implementation of a confidence calibration system for face recognition, ensuring more accurate match probabilities. These updates enhance the project's documentation and provide insights for future improvements.

2026-01-06 13:11:30 -05:00

3.1 KiB

Raw Blame History

Monorepo Migration Summary

This document summarizes the migration from separate punimtag and punimtag-viewer projects to a unified monorepo structure.

Migration Date

December 2024

Changes Made

Directory Structure

Before:

punimtag/
├── src/web/          # Backend API
└── frontend/         # Admin React frontend

punimtag-viewer/      # Separate repository
└── (Next.js viewer)

After:

punimtag/
├── backend/          # FastAPI backend (renamed from src/web)
├── admin-frontend/   # React admin interface (renamed from frontend)
└── viewer-frontend/  # Next.js viewer (moved from punimtag-viewer)

Import Path Changes

All Python imports have been updated:

from src.web.* → from backend.*
import src.web.* → import backend.*

Configuration Updates

install.sh: Updated to install dependencies for both frontends
package.json: Created root package.json with workspace scripts
run_api_with_worker.sh: Updated to use backend.app instead of src.web.app
run_worker.sh: Updated to use backend.worker instead of src.web.worker
docker-compose.yml: Updated service commands to use backend.* paths

Environment Files

admin-frontend/.env: Backend API URL configuration
viewer-frontend/.env.local: Database and NextAuth configuration

Port Configuration

Admin Frontend: Port 3000 (unchanged)
Viewer Frontend: Port 3001 (configured in viewer-frontend/package.json)
Backend API: Port 8000 (unchanged)

Running the Application

Development

Terminal 1 - Backend:

source venv/bin/activate
export PYTHONPATH=$(pwd)
uvicorn backend.app:app --host 127.0.0.1 --port 8000

Terminal 2 - Admin Frontend:

cd admin-frontend
npm run dev

Terminal 3 - Viewer Frontend:

cd viewer-frontend
npm run dev

Using Root Scripts

# Install all dependencies
npm run install:all

# Run individual services
npm run dev:backend
npm run dev:admin
npm run dev:viewer

Benefits

Unified Setup: Single installation script for all components
Easier Maintenance: All code in one repository
Shared Configuration: Common environment variables and settings
Simplified Deployment: Single repository to deploy
Better Organization: Clear separation of admin and viewer interfaces

Migration Checklist

Rename src/web to backend
Rename frontend to admin-frontend
Copy punimtag-viewer to viewer-frontend
Update all Python imports
Update all scripts
Update install.sh
Create root package.json
Update docker-compose.yml
Update README.md
Update scripts in scripts/ directory

Notes

The viewer frontend manages the punimtag_auth database
Both frontends share the main punimtag database
Backend API serves both frontends
All database schemas remain unchanged

Next Steps

Test all three services start correctly
Verify database connections work
Test authentication flows
Update CI/CD pipelines if applicable
Archive or remove the old punimtag-viewer repository

3.1 KiB Raw Blame History