🎨 Kolam Learning Platform

Preserving Cultural Heritage Through AI Technology

---

📖 Table of Contents

• 🎯 Overview
• ✨ Features
• 🛠️ Tech Stack
• 🏗️ Architecture
• 📁 Project Structure
• 🚀 Quick Start
• ⚙️ Configuration
• 📊 API Documentation
• 🧪 Testing
• 🐳 Docker Support
• 📊 Monitoring
• 🤝 Contributing
• 📝 License
• 👥 Team
• 📞 Support

---

🎯 Overview

An AI-powered platform for learning, exploring, and celebrating the traditional Indian art of Kolam (also known as muggu, rangoli, and rangavalli). This innovative platform seamlessly blends cultural heritage with cutting-edge technology to provide immersive, interactive learning experiences.

🌟 Mission: To preserve and promote traditional Indian art forms through modern AI technology while making cultural learning accessible, engaging, and globally available.

🎨 What is Kolam?

Kolam is a traditional South Indian art form where intricate patterns are drawn using rice flour, chalk, or colored powders. These beautiful geometric designs are typically created at the entrance of homes and temples, symbolizing prosperity, protection, and welcome to visitors.

✨ Features

🧠 AI-Powered	📚 Interactive Learning	🌐 Community	🔧 Technical
Pattern Detection	Gamified Quizzes	Pattern Sharing	Real-time Processing
AI Generation	Progress Tracking	Collaborative Learning	Offline Capability
Smart Recognition	Cultural Context	Community Gallery	Cross-platform
LLM Integration	Adaptive Difficulty	Cultural Exchange	Scalable Architecture

🧠 AI-Powered Capabilities

🔍 Advanced Pattern Recognition

• Smart Detection: Upload images and get instant AI-powered analysis of Kolam patterns
• Cultural Classification: Identify traditional patterns and their regional variations
• Accuracy Scoring: Get detailed feedback on pattern accuracy and completeness
• Pattern Similarity: Find similar patterns in the database with confidence scores

🎨 Intelligent Generation

• Mathematical Algorithms: Create new Kolam designs using geometric principles
• AI-Assisted Design: Generate patterns based on user preferences and skill level
• Style Transfer: Apply traditional styles to modern interpretations
• Custom Variations: Create personalized versions of classical patterns

🤖 AI-Powered Learning Assistant

• Interactive Hints: Get contextual help when stuck on patterns
• Cultural Insights: Learn about symbolism and meaning through AI explanations
• Personalized Feedback: Receive tailored suggestions for improvement
• Local LLM Integration: Powered by Ollama for privacy-focused AI interactions

📚 Interactive Learning Experience

🎮 Gamified Education

• Duolingo-style Progression: Step-by-step learning with clear milestones
• Achievement System: Unlock badges and rewards for completing challenges
• Streak Tracking: Maintain daily practice streaks for consistent learning
• Leaderboards: Compete with friends and community members

📈 Adaptive Learning Path

• Skill Assessment: Initial evaluation to determine starting level
• Dynamic Difficulty: Automatic adjustment based on performance
• Personalized Curriculum: Tailored learning path for each user
• Progress Analytics: Detailed insights into learning patterns and improvements

🌐 Community & Collaboration

🤝 Social Learning

• Pattern Gallery: Showcase and discover community creations
• Collaborative Projects: Work together on complex multi-part designs
• Mentorship Program: Connect beginners with experienced practitioners
• Cultural Ambassadors: Learn from traditional artists and experts

🔧 Technical Excellence

⚡ Performance & Reliability

• Sub-second Analysis: Lightning-fast pattern recognition and feedback
• 99.9% Uptime: Robust infrastructure with automatic failover
• Offline Mode: Continue learning without internet connectivity
• Cross-platform: Seamless experience across web, mobile, and desktop

🔝 Back to Top

�️ Tech Stack

Backend Technologies

Frontend Technologies

AI/ML Stack

Database & Storage

DevOps & Monitoring

📊 Detailed Technology Breakdown

Category	Technology	Version	Purpose
Web Framework	FastAPI	0.104+	High-performance async API framework
Frontend Framework	React	19.1+	Modern UI library with hooks
Build Tool	Vite	7.1+	Fast development and build tool
Database ORM	SQLAlchemy	2.0+	Python SQL toolkit and ORM
Migration Tool	Alembic	1.12+	Database migration management
AI Framework	TensorFlow	2.15+	Deep learning and pattern recognition
Computer Vision	OpenCV	4.8+	Image processing and analysis
LLM Integration	Ollama	0.1+	Local language model inference
Search Engine	OpenSearch	2.11+	Vector search and full-text search
Monitoring	Prometheus + Grafana	Latest	Metrics collection and visualization
Authentication	JWT + OAuth2	-	Secure user authentication
Validation	Pydantic	2.5+	Data validation and serialization

🔝 Back to Top

🏗️ Architecture

graph TB
    subgraph "Frontend Layer"
        UI[React Frontend]
        Mobile[Mobile App]
    end
    
    subgraph "API Gateway"
        FastAPI[FastAPI Server]
        Auth[Authentication]
        Rate[Rate Limiting]
    end
    
    subgraph "Core Services"
        Kolam[Kolam Service]
        Learning[Learning Service]
        User[User Service]
        AI[AI Service]
    end
    
    subgraph "AI/ML Pipeline"
        Detection[Pattern Detection]
        Generation[Pattern Generation]
        Ollama[LLM Service]
        CV[Computer Vision]
    end
    
    subgraph "Data Layer"
        Postgres[(PostgreSQL)]
        Search[(OpenSearch)]
        Files[(File Storage)]
        Cache[(Redis Cache)]
    end
    
    subgraph "Infrastructure"
        Docker[Docker Containers]
        Monitor[Monitoring]
        Logs[Logging]
    end
    
    UI --> FastAPI
    Mobile --> FastAPI
    FastAPI --> Auth
    FastAPI --> Rate
    FastAPI --> Kolam
    FastAPI --> Learning
    FastAPI --> User
    
    Kolam --> AI
    Learning --> AI
    AI --> Detection
    AI --> Generation
    AI --> Ollama
    AI --> CV
    
    Kolam --> Postgres
    Learning --> Postgres
    User --> Postgres
    AI --> Search
    AI --> Files
    FastAPI --> Cache
    
    FastAPI --> Monitor
    FastAPI --> Logs

Loading

🔄 System Flow

📸 Image Processing Workflow

User Upload → Image Validation → AI Detection → Pattern Analysis → 
Cultural Classification → Feedback Generation → Results Display

1. Image Input: User uploads Kolam image
2. Preprocessing: Image normalization and enhancement
3. AI Detection: EfficientNet-B4 model analyzes patterns
4. Pattern Matching: Compare against traditional pattern database
5. Cultural Context: LLM provides cultural insights and explanations
6. Results: Comprehensive feedback with suggestions

🎓 Learning Path Engine

Skill Assessment → Personalized Curriculum → Progressive Challenges → 
Performance Analytics → Adaptive Difficulty → Mastery Tracking

1. Initial Assessment: Evaluate user's current skill level
2. Path Generation: Create personalized learning trajectory
3. Content Delivery: Serve appropriate challenges and tutorials
4. Progress Monitoring: Track completion rates and accuracy
5. Dynamic Adjustment: Modify difficulty based on performance
6. Achievement Unlocking: Reward progress with badges and certificates

🗃️ Database Schema Overview

📊 Core Data Models

-- Users and Authentication
users (id, email, username, created_at, profile_data)
user_sessions (id, user_id, token, expires_at)

-- Kolam Patterns and Analysis
kolam_patterns (id, name, region, difficulty, cultural_significance)
user_uploads (id, user_id, image_path, analysis_results, created_at)
pattern_detections (id, upload_id, pattern_id, confidence_score)

-- Learning and Progress
learning_paths (id, user_id, current_level, progress_percentage)
quiz_attempts (id, user_id, quiz_id, score, completed_at)
achievements (id, user_id, badge_type, earned_at)

-- Community and Social
shared_patterns (id, user_id, pattern_id, public, likes_count)
comments (id, pattern_id, user_id, content, created_at)

🔝 Back to Top

• Python 3.11 or higher
• uv package manager
• Git

Option 1: SQLite (Recommended for Development)

No database setup required! The application works out of the box with SQLite.

# Clone the repository
git clone https://github.com/your-org/kolam-learning-platform.git
cd kolam-learning-platform

# Install dependencies
uv sync

# Start the development server
.\dev.bat dev  # Windows
# or
make dev       # Linux/macOS

That's it! 🎉 Your server will be running at http://localhost:8000

Option 2: Full Stack with PostgreSQL

For production or advanced features:

# Start all services with Docker
.\dev.bat docker-up  # Windows
# or
docker-compose up -d  # Linux/macOS

# Run database migrations
.\dev.bat migrate-up

# Start the development server
.\dev.bat dev

📖 API Documentation

Once the server is running, access the interactive API documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• Health Check: http://localhost:8000/health

� Project Structure

🎨 kolam-learning-platform/
├── 📁 src/                          # 🐍 Backend Source Code
│   ├── 📁 api/                      # 🌐 FastAPI Routes & Endpoints
│   │   ├── 🔐 auth.py               # Authentication & Authorization
│   │   ├── 🎨 kolam.py              # Kolam Detection & Analysis
│   │   ├── 📚 learning.py           # Learning Platform Features
│   │   └── 👤 users.py              # User Management
│   ├── 📁 core/                     # ⚙️ Core Configuration
│   │   ├── 🔧 config.py             # App Settings & Environment
│   │   ├── 🗄️ database.py           # Database Configuration
│   │   ├── 📝 logging.py            # Structured Logging Setup
│   │   └── 🔒 security.py           # Security Utilities
│   ├── 📁 services/                 # �🛠️ Business Logic Layer
│   │   ├── 📁 ai/                   # 🤖 AI/ML Services
│   │   │   ├── 🔍 detection_service.py    # Pattern Recognition
│   │   │   ├── 🎨 generation_service.py   # Pattern Generation
│   │   │   └── 🧠 ollama_service.py       # LLM Integration
│   │   ├── 🔐 auth_service.py       # Authentication Logic
│   │   ├── 🎨 kolam_service.py      # Kolam Business Logic
│   │   ├── 📚 learning_service.py   # Learning Platform Logic
│   │   └── 👤 user_service.py       # User Management Logic
│   ├── 📁 schemas/                  # 📋 Pydantic Models
│   ├── 📁 search/                   # 🔍 Search Integration
│   │   └── 🔌 client.py             # OpenSearch Client
│   └── 🚀 main.py                   # Application Entry Point
├── 📁 frontend/                     # ⚛️ React Frontend
│   └── 📁 SIH-F-main/               # 🎨 Main Frontend App
│       ├── 📁 src/
│       │   ├── 📁 components/       # 🧩 React Components
│       │   │   ├── 🏠 home.jsx      # Landing Page
│       │   │   ├── 🔍 recognize.jsx # Pattern Recognition
│       │   │   ├── 🎨 AiRecreate.jsx # AI Generation
│       │   │   ├── 📚 knowledge.jsx # Learning Hub
│       │   │   ├── 🎯 quiz.jsx      # Interactive Quizzes
│       │   │   └── 📊 analysis.jsx  # Analytics Dashboard
│       │   ├── 📁 services/         # 🌐 API Integration
│       │   └── 📁 data/             # 📊 Static Data
│       ├── 📦 package.json          # Dependencies & Scripts
│       └── ⚡ vite.config.js        # Build Configuration
├── 📁 Finetuning/                   # 🧠 ML Model Training
│   ├── 🔬 finetune.py               # Model Fine-tuning Script
│   ├── 📊 graph.py                  # Training Visualization
│   └── 🤖 kolam_efficientnet_b4.pth # Trained Model Weights
├── 📁 tests/                        # 🧪 Test Suite
│   ├── 🌐 test_api_endpoints.py     # API Integration Tests
│   ├── 🔍 test_kolam_detection.py   # AI Detection Tests
│   └── 🎨 test_kolam_generation.py  # Generation Tests
├── 📁 monitoring/                   # 📊 Observability Stack
│   ├── 📈 prometheus.yml            # Metrics Configuration
│   └── 📁 grafana/                  # Dashboard Definitions
├── 📁 scripts/                      # 🛠️ Utility Scripts
│   ├── 🔍 inference.py              # Model Inference Script
│   ├── 🗄️ init-db.sql              # Database Initialization
│   └── 🧠 KNOWLEDGE.py              # Knowledge Base Setup
├── 📁 alembic/                      # 🔄 Database Migrations
│   ├── ⚙️ env.py                    # Migration Environment
│   └── 📁 versions/                 # Migration Files
├── 🐳 docker-compose.yml            # Multi-Service Orchestration
├── 🐳 Dockerfile                    # Container Definition
├── 📋 pyproject.toml                # Python Project Configuration
├── 📦 requirements.txt              # Python Dependencies
├── ⚙️ alembic.ini                   # Migration Configuration
├── 🔧 Makefile                      # Development Commands
├── 🖥️ dev.bat                       # Windows Development Script
└── 📖 README.md                     # Project Documentation

📝 Directory Descriptions

Directory	Purpose	Key Files
src/api/	REST API endpoints and routing	auth.py, kolam.py, learning.py
src/services/	Business logic and service layer	*_service.py files
src/services/ai/	AI/ML processing services	detection_service.py, ollama_service.py
frontend/SIH-F-main/	React frontend application	App.jsx, component files
Finetuning/	Machine learning model training	finetune.py, model weights
tests/	Automated test suite	Test files for all components
monitoring/	Observability and monitoring	Prometheus, Grafana configs
alembic/	Database schema migrations	Version-controlled DB changes
scripts/	Development and deployment utilities	Setup and utility scripts

🔝 Back to Top

🚀 Quick Start

📋 Prerequisites

Command	Description
.\dev.bat dev	Start development server with hot reload
.\dev.bat test	Run all tests
.\dev.bat format	Format code with ruff
.\dev.bat lint	Lint code with ruff
.\dev.bat docker-up	Start all Docker services
.\dev.bat docker-down	Stop all Docker services
.\dev.bat migrate-up	Run database migrations
.\dev.bat migrate-down	Rollback database migrations
.\dev.bat setup	Run initial setup

Linux/macOS Commands

# Development
make dev              # Start development server
make test             # Run tests
make format           # Format code
make lint             # Lint code
make docker-up        # Start Docker services
make docker-down      # Stop Docker services

# Code Quality
ruff check src/       # Lint code
ruff format src/      # Format code
mypy src/            # Type checking
pytest               # Run tests
pre-commit run --all-files  # Run pre-commit hooks

🏗️ Project Structure

kolam-learning-platform/
├── 📁 src/
│   ├── 📁 api/              # FastAPI routers and endpoints
│   │   ├── auth.py          # Authentication endpoints
│   │   ├── kolam.py         # Kolam-related endpoints
│   │   ├── learning.py      # Learning platform endpoints
│   │   └── users.py         # User management endpoints
│   ├── 📁 core/             # Core configuration and utilities
│   │   ├── config.py        # Application settings
│   │   ├── database.py      # Database configuration
│   │   ├── logging.py       # Logging setup
│   │   └── security.py      # Security utilities
│   ├── 📁 db/               # Database models and migrations
│   │   └── models/          # SQLAlchemy models
│   ├── 📁 services/         # Business logic services
│   │   ├── 📁 ai/           # AI/ML services
│   │   │   ├── detection_service.py    # Kolam detection
│   │   │   ├── generation_service.py   # Pattern generation
│   │   │   └── ollama_service.py       # LLM integration
│   │   ├── auth_service.py  # Authentication logic
│   │   ├── kolam_service.py # Kolam business logic
│   │   ├── learning_service.py # Learning platform logic
│   │   └── user_service.py  # User management logic
│   ├── 📁 schemas/          # Pydantic models for API
│   ├── 📁 search/           # OpenSearch integration
│   └── main.py              # Application entry point
├── 📁 tests/                # Test files
├── 📁 monitoring/           # Monitoring and observability
│   ├── 📁 grafana/          # Grafana dashboards
│   └── prometheus.yml       # Prometheus configuration
├── 📁 scripts/              # Utility scripts
├── 📁 uploads/              # File uploads directory
├── 📁 generated_images/     # AI-generated images
├── 📁 logs/                 # Application logs
├── docker-compose.yml       # Docker services configuration
├── Dockerfile              # Container configuration
├── pyproject.toml          # Python project configuration
├── requirements.txt        # Python dependencies
├── alembic.ini            # Database migration configuration
└── README.md              # This file

🧪 Testing

# Run all tests
.\dev.bat test  # Windows
make test       # Linux/macOS

# Run specific test categories
pytest tests/test_api_endpoints.py
pytest tests/test_kolam_detection.py
pytest tests/test_kolam_generation.py

# Run with coverage
pytest --cov=src tests/

🐳 Docker Support

The platform includes comprehensive Docker support for all services:

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

# Rebuild and start
docker-compose up --build -d

Services Included:

• PostgreSQL: Primary database
• OpenSearch: Search and vector operations
• Ollama: Local LLM for AI features
• Redis: Caching and session storage
• Prometheus: Metrics collection
• Grafana: Monitoring dashboards

🔧 Configuration

Environment Variables

Create a .env file in the project root:

# Database Configuration
DATABASE_URL=sqlite:///./kolam.db  # For development
# DATABASE_URL=postgresql://user:pass@localhost:5432/kolam_db  # For production

# AI/ML Configuration
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama2

# Security
SECRET_KEY=your-secret-key-here
ACCESS_TOKEN_EXIRE_MINUTES=30

# Application Settings
DEBUG=true
LOG_LEVEL=INFO

Database Options

1. SQLite (Default - No setup required)

   • Perfect for development
   • No external dependencies
   • File-based database

2. PostgreSQL (Production recommended)

   • Better performance
   • Advanced features
   • Requires Docker or local installation

📊 Monitoring & Observability

The platform includes comprehensive monitoring:

• Health Checks: /health endpoint
• Metrics: Prometheus integration
• Logging: Structured logging with context
• Tracing: OpenTelemetry support
• Dashboards: Grafana visualizations

Access monitoring at:

• Grafana: http://localhost:3000 (admin/admin)
• Prometheus: http://localhost:9090

🤝 Contributing

We welcome contributions from developers, designers, cultural experts, and art enthusiasts! 🎨

🌟 How to Contribute

🚀 Development Workflow

1. 🍴 Fork the repository
2. 🌿 Create a feature branch: git checkout -b feature/amazing-feature
3. 💻 Develop your changes with tests
4. 🧪 Test your code: .\dev.bat test
5. ✨ Format code: .\dev.bat format
6. 📝 Commit changes: git commit -m 'Add amazing feature'
7. 📤 Push to branch: git push origin feature/amazing-feature
8. 🔄 Open a Pull Request

🎯 Contribution Areas

Area	Skills Needed	Impact
🤖 AI/ML	TensorFlow, PyTorch, CV	High
🌐 Backend	FastAPI, Python, SQL	High
⚛️ Frontend	React, JavaScript, CSS	High
🎨 UI/UX	Design, Figma, User Research	Medium
📚 Documentation	Writing, Markdown	Medium
🧪 Testing	Pytest, Testing Strategies	Medium
🌍 Cultural Content	Kolam Knowledge, Art History	High
🔧 DevOps	Docker, CI/CD, Monitoring	Medium

📋 Contribution Guidelines

• Code Quality: Follow PEP 8 for Python, ESLint for JavaScript
• Testing: Write tests for new features and bug fixes
• Documentation: Update docs for any API or feature changes
• Cultural Sensitivity: Respect traditional art forms and cultural significance
• Commit Messages: Use conventional commits format

🎨 Cultural Contributions

We especially welcome contributions from:

• Traditional Artists - Share authentic patterns and cultural knowledge
• Art Historians - Provide historical context and regional variations
• Cultural Experts - Ensure accuracy and respectful representation
• Regional Specialists - Add patterns from different Indian states

🔝 Back to Top

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🎯 What this means:

• ✅ Commercial use - Use in commercial projects
• ✅ Modification - Modify and adapt the code
• ✅ Distribution - Share and distribute freely
• ✅ Private use - Use for personal projects
• ⚠️ Attribution required - Include original license

---

👥 Team

🏆 TechTitans Development Team

Name	Role	GitHub	Specialization
Janhvi Bisht	🎨 Frontend Lead	@janhvi	React, UI/UX Design
Kartikeya Trivedi	🧠 AI/ML Engineer	@Kartikeya-trivedi	Deep Learning, Computer Vision
Krishna Gupta	🌐 Backend Lead	@krishna	FastAPI, Database Design
Kushagra Chaudhary	🔧 DevOps Engineer	@kushagra	Docker, CI/CD, Infrastructure
Nakshatra Vidyarthi	📱 Full-stack Developer	@nakshatra	React, Python, API Integration
Rounak Gope	🧪 QA Engineer	@rounak	Testing, Quality Assurance

🎯 Project Statistics

---

📞 Support

🆘 Need Help?

📧 Contact Information

Channel	Contact	Response Time
📧 Email	[email protected]	24-48 hours
🐛 Bug Reports	GitHub Issues	24 hours
💡 Feature Requests	GitHub Discussions	48 hours
📚 Documentation	Project Wiki	Always Available

🤔 Frequently Asked Questions

🎨 How accurate is the pattern recognition?

Our EfficientNet-B4 model achieves 95%+ accuracy on traditional Kolam patterns. Accuracy may vary for modern interpretations or incomplete patterns.

🌐 Can I use this offline?

Yes! The platform supports offline mode for basic pattern recognition and learning modules. AI-powered features require internet connectivity.

📱 Is there a mobile app?

Currently, we offer a responsive web application. A dedicated mobile app is in our roadmap for 2024.

🎓 Is this suitable for children?

Absolutely! The platform is designed to be family-friendly and educational, suitable for ages 8 and up with parental guidance.

---

🗺️ Roadmap

🚀 What's Next?

📅 2024 Q1 - Q2

• 📱 Mobile App (React Native)
• 🧠 Advanced AI pattern recognition
• 🌐 Multi-language support (Tamil, Telugu, Hindi)
• 🎨 3D Kolam visualization
• 🤝 Social features and community forums

📅 2024 Q3 - Q4

• 🥽 AR/VR integration for immersive learning
• 📚 Educational curriculum for schools
• 🎮 Gamification enhancements
• 🌍 Global expansion to other traditional arts
• 🤖 AI tutor for personalized guidance

📅 2025 and Beyond

• 🧬 Blockchain for pattern authenticity
• 🎪 Virtual exhibitions and galleries
• 👩‍🏫 Master craftsperson video tutorials
• 🌊 Real-time collaboration on patterns
• 🏆 Certification program for traditional arts

---

🙏 Acknowledgments

💖 Special Thanks

• 🎨 Traditional Artists - For preserving and sharing this beautiful art form
• 🏛️ Cultural Institutions - For historical patterns and cultural context
• 🌍 Open Source Community - For the amazing tools and libraries
• 👥 Beta Testers - For valuable feedback and testing
• 🏫 Educational Partners - For curriculum guidance and testing
• 💻 Technology Partners - For infrastructure and AI model support

🛠️ Built With Love Using

---

🌟 Star us on GitHub!

If you find this project helpful, please consider giving it a ⭐

---

Made with ❤️ by the TechTitans team

🎨 Preserving cultural heritage through technology 🚀

---

🔝 Back to Top