# 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