game-library/README.md

INDEX-SISTEM-JOCURI v2.0

🎯 Advanced Activity Indexing and Search System for Educational Games

A professional Flask-based web application that indexes and provides advanced search capabilities for 500+ educational activities, games, and exercises for children and youth groups.

🚀 Features

Core Functionality

• Advanced Activity Parser: Extracts activities from INDEX_MASTER_JOCURI_ACTIVITATI.md
• Full-Text Search: SQLite FTS5-powered search with Romanian diacritics support
• Dynamic Filters: Real-time filtering by category, age group, participants, duration, materials
• Responsive Design: Clean, minimalist interface optimized for all devices
• Activity Details: Comprehensive activity sheets with recommendations

Technical Highlights

• Production-Ready: Docker containerization with docker-compose
• Database: SQLite with FTS5 full-text search indexing
• Architecture: Clean Flask application with modular design
• Dependencies: Pipenv for dependency management
• Search Performance: Optimized for 500+ activities with sub-second response times

📊 Current Status

• ✅ 63 Activities Indexed (from basic patterns)
• ✅ 8 Categories covered
• ✅ Full-Text Search operational
• ✅ Dynamic Filters functional
• ✅ Web Interface responsive and accessible
• ✅ Docker Ready for production deployment

🏗️ Architecture

INDEX-SISTEM-JOCURI/
├── app/                      # Flask application
│   ├── models/              # Data models and database
│   ├── services/            # Business logic (parser, indexer, search)
│   ├── web/                 # Web routes and controllers
│   ├── templates/           # Jinja2 templates
│   └── static/              # CSS, JS, images
├── data/                    # Database and data files
├── scripts/                 # Utility scripts
├── docs/                    # Documentation
├── Dockerfile              # Container definition
├── docker-compose.yml      # Multi-service orchestration
└── Pipfile                  # Python dependencies

🛠️ Installation & Setup

Option 1: Docker (Recommended)

# Clone repository
git clone <repository-url>
cd INDEX-SISTEM-JOCURI

# Build and start services
docker-compose up --build

# Access application
open http://localhost:5000

Option 2: Local Development

# Install Pipenv if not already installed
pip install pipenv

# Install dependencies
pipenv install

# Activate virtual environment
pipenv shell

# Index activities from INDEX_MASTER
python scripts/index_data.py --clear

# Start application
python app/main.py

📚 Usage

Web Interface

1. Main Search: Navigate to http://localhost:5000
2. Filter Activities: Use dropdown filters for precise results
3. View Details: Click activity titles for comprehensive information
4. Health Check: Monitor at http://localhost:5000/health

Command Line Tools

# Index all activities
python scripts/index_data.py --clear

# Index specific category
python scripts/index_data.py --category "[A]"

# View database statistics
python scripts/index_data.py --stats

# Verify indexing quality
python scripts/index_data.py --verify

🔍 Search Features

Full-Text Search

• Romanian Diacritics: Automatic handling of ă, â, î, ș, ț
• Phrase Search: Exact phrase matching with fallback
• Relevance Ranking: Intelligent scoring based on title, description, keywords

Advanced Filters

• Category: 8 main activity categories
• Age Group: Specific age ranges (5-8, 8-12, 12-16, 16+)
• Participants: Group size filtering
• Duration: Time-based activity selection
• Materials: Filter by required materials
• Difficulty: Activity complexity levels

API Endpoints

• GET /api/search?q=keyword - JSON search results
• GET /api/statistics - Database statistics
• GET /api/filters - Available filter options
• GET /health - Application health status

🗄️ Database Schema

Activities Table

• Basic Info: name, description, rules, variations
• Categories: category, subcategory
• Parameters: age_group_min/max, participants_min/max, duration_min/max
• Materials: materials_category, materials_list
• Metadata: keywords, tags, popularity_score, source info

Search Index (FTS5)

• Full-Text: name, description, rules, variations, keywords
• Performance: Optimized for 500+ activities
• Triggers: Automatic sync with main table

🎯 Data Sources

The system processes activities from INDEX_MASTER_JOCURI_ACTIVITATI.md containing:

• Total Files Analyzed: 200+
• Total Activities Catalogued: 2000+
• Current Extraction: 63 activities from explicit patterns
• Enhancement Potential: Parser can be extended for 500+ activities

Categories Covered

1. [A] Jocuri Cercetășești și Scout (38 activities)
2. [B] Team Building și Comunicare (3 activities)
3. [C] Camping și Activități Exterior (6 activities)
4. [D] Escape Room și Puzzle-uri (2 activities)
5. [E] Orientare și Busole (3 activities)
6. [F] Primul Ajutor și Siguranță (3 activities)
7. [G] Activități Educaționale (5 activities)
8. [H] Resurse Speciale (3 activities)

🚀 Deployment

Production Environment

# Set environment variables
export FLASK_ENV=production
export SECRET_KEY=your-secure-secret-key
export DATABASE_URL=/app/data/activities.db

# Start with docker-compose
docker-compose -f docker-compose.yml up -d

Environment Variables

• FLASK_ENV: application environment (development/production)
• SECRET_KEY: Flask secret key for sessions
• DATABASE_URL: SQLite database path
• SEARCH_RESULTS_LIMIT: Maximum search results (default: 100)

🧪 Testing

Manual Testing

# Test search functionality
curl "http://localhost:5000/api/search?q=acting"

# Check application health
curl http://localhost:5000/health

# View database statistics
curl http://localhost:5000/api/statistics

🔧 Development

Managing Dependencies

# Install new package
pipenv install package-name

# Install development dependencies
pipenv install package-name --dev

# Update dependencies
pipenv update

# Generate requirements.txt (if needed for compatibility)
pipenv requirements > requirements.txt

Adding New Activities

1. Update INDEX_MASTER_JOCURI_ACTIVITATI.md
2. Run python scripts/index_data.py --clear
3. Verify with python scripts/index_data.py --stats

Enhancing the Parser

• Modify app/services/parser.py to extract more patterns
• Add new extraction methods in _parse_subsections()
• Test changes with specific categories

📈 Performance

Current Metrics

• Index Time: ~0.5 seconds for 63 activities
• Search Response: <100ms average
• Database Size: ~116KB
• Memory Usage: <50MB

Optimization Features

• SQLite FTS5 for full-text search
• Indexed columns for filters
• Connection pooling
• Query optimization

🛡️ Security

Implemented Measures

• Input sanitization and validation
• SQL injection protection via parameterized queries
• Path traversal protection for file access
• Non-root Docker container execution
• Environment variable configuration

Production Considerations

• Set secure SECRET_KEY
• Use HTTPS in production
• Regular database backups
• Monitor application logs

🤝 Contributing

Development Setup

1. Fork repository
2. Create feature branch
3. Install development dependencies: pipenv install --dev
4. Run tests and linting
5. Submit pull request

Code Standards

• Python: Follow PEP 8
• JavaScript: ES6+ standards
• CSS: BEM methodology
• HTML: Semantic HTML5

📄 License

This project is developed for educational purposes. Please respect the intellectual property of the original activity sources referenced in INDEX_MASTER_JOCURI_ACTIVITATI.md.

🔗 Resources

• Flask Documentation: https://flask.palletsprojects.com/
• SQLite FTS5: https://www.sqlite.org/fts5.html
• Docker Compose: https://docs.docker.com/compose/
• Pipenv: https://pipenv.pypa.io/

---

INDEX-SISTEM-JOCURI v2.0 - Transforming educational activity discovery through advanced search and indexing technology.

🎯 Ready for production deployment with 63+ indexed activities and full search capabilities.