punimtag/docs/structure.md

PunimTag Project Structure

Directory Organization

PunimTag/
├── src/                    # Main application source code
│   ├── backend/           # Flask backend and API
│   ├── frontend/          # JavaScript and UI components
│   └── utils/             # Utility functions and helpers
├── docs/                  # Documentation and steering documents
├── tests/                 # All test files and test utilities
├── data/                  # Database files and user data
├── assets/                # Static assets (images, CSS, etc.)
├── config/                # Configuration files
└── scripts/               # Build and deployment scripts

Core Components

Backend (Flask)

• Main Application: simple_web_gui.py - Primary Flask app
• Database Management: db_manager.py - Database operations
• Face Recognition: visual_identifier.py - Face detection and recognition
• Configuration: config.py - App configuration

Frontend (JavaScript)

• UI Components: Embedded in Flask templates
• Progressive Loading: Handles large photo collections
• Custom Dialogs: Replaces browser alerts
• Face Management: Face identification and tagging interface

Data Layer

• SQLite Database: punimtag_simple.db - Main database
• Image Storage: photos/ directory
• Thumbnails: Generated on-demand
• Face Encodings: Stored as binary data

Architecture Principles

1. Separation of Concerns

• Backend: Business logic, data processing, API endpoints
• Frontend: User interface, interactions, state management
• Data: Persistent storage, caching, optimization

2. Progressive Enhancement

• Core Functionality: Works without JavaScript
• Enhanced Features: Progressive loading, real-time updates
• Fallbacks: Graceful degradation for older browsers

3. Performance Optimization

• Lazy Loading: Images and data loaded on demand
• Caching: Thumbnails and frequently accessed data
• Batch Operations: Efficient bulk processing

4. User Experience

• Responsive Design: Works on all screen sizes
• Accessibility: Keyboard navigation, screen reader support
• Error Handling: Graceful error recovery and user feedback

File Naming Conventions

Python Files

• snake_case for file names and functions
• PascalCase for classes
• UPPER_CASE for constants

JavaScript Files

• camelCase for functions and variables
• PascalCase for classes and components
• kebab-case for CSS classes

Database

• snake_case for table and column names
• Descriptive names that clearly indicate purpose

Dependencies

Backend Dependencies

• Flask: Web framework
• SQLite: Database
• dlib: Face recognition
• Pillow: Image processing
• numpy: Numerical operations

Frontend Dependencies

• Vanilla JavaScript: No external frameworks
• CSS Grid/Flexbox: Layout system
• Fetch API: HTTP requests
• Intersection Observer: Progressive loading

Configuration Management

• Environment Variables: For sensitive data
• JSON Config Files: For application settings
• Database Migrations: For schema changes
• Feature Flags: For experimental features