Skip to content

itsma3il/SIRA

BranchesTags

Repository files navigation

SIRA - Système Intelligent de Recommandation Académique

AI-Powered Academic Recommendation Platform for Students

Production Ready Tests Passing Documentation License

🎯 What is SIRA?

SIRA is a next-generation academic advisory platform that uses RAG (Retrieval-Augmented Generation) technology to help students discover personalized university programs and career paths.

Key Features

  • 🤖 AI-Powered Recommendations - Personalized program suggestions based on your profile
  • 💬 Real-time Chat Advisor - Interactive AI assistant for instant academic guidance
  • 📊 Visual Insights - Match scores, timelines, and comparison charts
  • 🎓 Multi-Profile Support - Manage multiple academic profiles
  • 🌍 Comprehensive Database - Programs from Morocco and international institutions
  • 📱 Mobile-Responsive - Access from any device

🚀 Quick Start

Prerequisites

  • Docker & Docker Compose (recommended)
  • Python 3.12+ & Node.js 18+ (for local development)
  • PostgreSQL 17, Pinecone, Mistral AI (API keys required)

One-Command Startup (Docker)

# Clone the repository
git clone https://github.com/yourorg/sira.git
cd sira

# Start all services
docker-compose up -d

# Access the application
# Frontend: http://localhost:3000
# Backend API: http://localhost:8000/docs

Local Development

# Backend
cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

# Frontend
cd frontend
bun install
bun dev

📚 Documentation

Full documentation available in the docs/ folder:

Quick Links

By Role

Role Start Here
Students User Guide
Developers Developer Guide
DevOps Deployment Guide
Project Managers Project Status

Key Documents

💡 Tip: Press Ctrl+K (or ⌘K on Mac) in the frontend to search all documentation!

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│              Next.js 16 Frontend                     │
│  React 19 • TypeScript • Tailwind CSS • Clerk Auth │
└────────────────────┬────────────────────────────────┘
                     │ HTTPS/JWT
┌────────────────────▼────────────────────────────────┐
│              FastAPI Backend                         │
│  Python 3.12 • PostgreSQL • LlamaIndex • Mistral AI│
└────────┬──────────┬──────────┬──────────────────────┘
         │          │          │
    ┌────▼───┐  ┌──▼─────┐  ┌─▼──────┐
    │PostgreSQL│ │Pinecone│ │Mistral │
    │Database  │ │Vector  │ │AI LLM  │
    └──────────┘ └────────┘ └────────┘

Tech Stack:

  • Frontend: Next.js 16, React 19, TypeScript, Tailwind CSS, Zustand
  • Backend: FastAPI, Python 3.12, SQLModel, PostgreSQL 17
  • AI/RAG: LlamaIndex, Mistral AI, Pinecone Vector Database
  • Auth: Clerk (JWT-based authentication)
  • Deployment: Docker, Docker Compose, Nginx

See Architecture Documentation for details.

🛠️ Development

Project Structure

sira/
├── frontend/              # Next.js 16 application
│   ├── app/              # App Router pages
│   ├── components/       # React components
│   ├── lib/              # API clients & utilities
│   └── hooks/            # Custom React hooks
│
├── backend/              # FastAPI application
│   ├── app/
│   │   ├── api/         # REST API endpoints
│   │   ├── core/        # Configuration
│   │   ├── models/      # Database models
│   │   ├── services/    # Business logic
│   │   └── utils/       # Helper functions
│   ├── alembic/         # Database migrations
│   └── tests/           # Backend tests
│
├── docs/                # Comprehensive documentation
│   ├── Developer Documentation/
│   ├── Operations Documentation/
│   ├── User Documentation/
│   └── Planning/
│
├── docker-compose.yml   # Multi-service orchestration
└── README.md           # This file

Common Commands

# Start all services
docker-compose up -d

# Run backend tests
cd backend && pytest

# Run frontend in dev mode
cd frontend && bun dev

# Check backend logs
docker-compose logs -f backend

# Restart services
docker-compose restart

🧪 Testing

  • Backend: 100/110 tests passing (91% pass rate)
  • Coverage: 52% → Target: 80%
  • E2E: Playwright tests for critical user flows
  • CI/CD: GitHub Actions for automated testing

See Testing Documentation for details.

📊 Project Status

Current Version: 1.0.0
Status: ✅ Production Ready
Release Date: January 30, 2026

Completed Phases (8/8)

  • ✅ Phase 1: Project Setup & Infrastructure
  • ✅ Phase 2: User Profile System
  • ✅ Phase 3: Knowledge Base & RAG Pipeline
  • ✅ Phase 4: Recommendation Engine
  • ✅ Phase 5: Conversational AI Interface
  • ✅ Phase 6: Frontend Integration
  • ✅ Phase 7: Feedback & Analytics
  • ✅ Phase 8: Testing & Deployment Preparation

Metrics

  • Tests: 100/110 passing (91%)
  • Code Coverage: 52%
  • Security Audit: ✅ Passed
  • Documentation: ✅ Complete (27,000+ lines)
  • Performance: ✅ Optimized

See Project Status for detailed roadmap.

🤝 Contributing

We welcome contributions! Please follow these steps:

  1. Read the docs: Developer Guide
  2. Fork the repository
  3. Create a feature branch: git checkout -b feature/amazing-feature
  4. Follow coding standards: Run linters before committing
  5. Write tests: Add tests for new features
  6. Submit a Pull Request

Development Guidelines

  • Follow the Architecture patterns
  • Write TypeScript with strict types
  • Use Python type hints
  • Add JSDoc/Docstring comments
  • Test your changes thoroughly

🔒 Security

Security is a top priority. SIRA implements:

  • ✅ JWT-based authentication (Clerk)
  • ✅ SSL/TLS encryption
  • ✅ Rate limiting & DDoS protection
  • ✅ Input validation & sanitization
  • ✅ SQL injection prevention
  • ✅ CORS configuration
  • ✅ Security headers (CSP, HSTS, etc.)

Found a vulnerability?

📞 Support

For Users

For Developers

📄 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

Built with:

Special thanks to all contributors and the open-source community.

Made with ❤️ by the SIRA Team

Documentation • API Reference • Report Bug

Documentation

Complete Documentation Index

Essential Guides

Technical Documentation

Implementation History

Testing

Run the comprehensive test suite:

# Run all tests
cd backend
./run_tests.sh

# Run unit tests only
./run_tests.sh --unit

# Run integration tests only
./run_tests.sh --integration

# Run with coverage report
./run_tests.sh --coverage

# Run specific test
pytest tests/test_validation.py -v

Test Coverage:

  • 76 total tests (62 unit, 14 integration)

  • 80% code coverage

  • Tests for validation, schemas, middleware, API endpoints

Security Features

SIRA implements multiple security layers:

Authentication & Authorization:

  • Clerk JWT validation on all protected endpoints
  • Role-based access control (user, admin)
  • Secure session management

Input Validation:

  • Pydantic schemas with custom validators
  • XSS prevention (HTML sanitization)
  • SQL injection protection
  • Path traversal prevention
  • URL validation

API Protection:

  • Rate limiting: 120 requests/minute, 2000/hour per IP
  • Security headers: HSTS, CSP, X-Frame-Options
  • CORS configuration
  • Request size limits

Data Security:

  • Environment variable validation at startup
  • Secure file upload handling
  • Database connection pooling with timeouts
  • Encrypted sensitive data

See docs/backend-security-hardening.md for details.

API Endpoints

Authentication

  • All endpoints require Clerk JWT except /health

Core Endpoints

Profiles:

  • POST /api/profiles - Create a new profile
  • GET /api/profiles - List all profiles for the authenticated user
  • GET /api/profiles/{id} - Get profile details
  • PUT /api/profiles/{id} - Update profile
  • PATCH /api/profiles/{id} - Partial update
  • DELETE /api/profiles/{id} - Delete profile

Recommendations:

  • GET /api/recommendations/{profile_id} - Get recommendations
  • POST /api/recommendations/{recommendation_id}/feedback - Submit feedback

Chat/Conversations:

  • POST /api/conversations - Create a new conversation
  • GET /api/conversations - List conversations
  • GET /api/conversations/{id}/stream - Stream AI responses (SSE)

Admin:

  • GET /api/admin/analytics - System analytics
  • GET /api/admin/feedback - Feedback trends
  • GET /api/admin/sessions - Active sessions

See docs/API_REFERENCE.md for complete API documentation.

Deployment

Production Checklist

  • Configure environment variables (see DEPLOYMENT_GUIDE.md)
  • Set up PostgreSQL 15+ with backups
  • Configure Pinecone index
  • Set up SSL/TLS certificates
  • Configure reverse proxy (Nginx)
  • Set up monitoring and logging
  • Run database migrations
  • Test health endpoints
  • Configure rate limiting
  • Set up backups and recovery

Docker Production Deploy

# Build production images
docker-compose -f docker-compose.prod.yml build

# Start services
docker-compose -f docker-compose.prod.yml up -d

# Run migrations
docker-compose exec backend alembic upgrade head

# Check health
curl http://localhost:8000/health

See docs/DEPLOYMENT_GUIDE.md for complete deployment procedures.

Development Roadmap

Completed (Phase 0-8)

Project setup and containerization
Authentication with Clerk
Profile management system
RAG infrastructure (LlamaIndex + Pinecone)
AI recommendation engine
Conversational AI interface
Admin dashboard and analytics
Feedback system
Security hardening
Comprehensive testing
Documentation

In Progress

Deployment preparation
Production deployment
Performance optimization

Future Enhancements

  • Mobile applications (React Native)
  • Advanced analytics and insights
  • Multi-language support
  • Graduate program recommendations
  • Integration with university application systems
  • Career trajectory predictions
  • Scholarship recommendations

Contributing

We welcome contributions! Please follow these guidelines:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes following the code style
  4. Write tests for new functionality
  5. Run the test suite: ./backend/run_tests.sh
  6. Commit your changes: git commit -m 'Add amazing feature'
  7. Push to the branch: git push origin feature/amazing-feature
  8. Open a Pull Request

Development Guidelines

  • Use Server Components for data fetching, Client Components for interactivity
  • Ensure TypeScript interfaces match Pydantic schemas
  • Always validate Clerk JWT on backend endpoints
  • Write tests for new features
  • Document complex logic with JSDoc/docstrings
  • Follow code style (ESLint, Black, isort)
  • Keep functions small and focused
  • Add comprehensive error handling

License

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

Team

SIRA Development Team
Master's Project - 2026

Support

Acknowledgments

  • Clerk for authentication infrastructure
  • Mistral AI for powerful LLM capabilities
  • Pinecone for vector database
  • Vercel for Next.js framework
  • FastAPI community
  • All open-source contributors

Built with using Next.js 16, FastAPI, and Mistral AI

About

SIRA is a Retrieval-Augmented Generation (RAG) academic advisor that delivers personalized university and career path recommendations. Built with the 2026 "Modern Stack": Next.js 16, FastAPI, LlamaIndex + Mistral AI, and Pinecone.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages