🏛️ ADHYA

Your Premier Full-Stack Tutor Matching & Live Learning Platform

---

ADHYA is a modern, premium full-stack mentor-matching and live-learning platform. Built with a highly responsive React + Tailwind v4 frontend and a robust FastAPI (Python) + PostgreSQL backend, ADHYA enables students to discover verified subject mentors, manage bookings, and communicate in real-time via persistent, permission-gated WebSockets.

Explore Backend Hub • Explore Frontend Application

---

🌟 Key Features

ADHYA is optimized for three user personas, providing dedicated dashboards and fine-grained authorization rules:

🎓 For Students

• Mentor Discovery: Search and discover expert tutors using multi-criteria filters including subject, city, monthly pricing, and minimum experience years.
• Booking Management: Book tutoring sessions directly based on real-time availability slots defined by mentors.
• Performance Reviews: Share structured rating scores (1–5) and written feedback for accepted bookings.
• Student Profile: Customize avatar, academic grade/class, and city.
• Hall of Fame: Showcase student achievements linked to specific tutors with vibrant visual cards.

👔 For Mentors / Teachers

• Teacher Dashboard: Real-time revenue trackers, active student counts, and booking request statistics.
• Availability Planner: Fully control active time slots organized by month and year.
• Hiring Portal: View incoming session requests with the ability to accept or decline student bookings.
• Professional Profiles: Edit professional biography, hourly rates, experience years, subject expertise, and location.

🛡️ For Administrators

• Platform Dashboard: Deep analytical dashboards showing active partnerships, overall revenue volume, and complete user breakdown.
• Mentor Verification: Secure onboarding flow where admins review, approve, and verify teachers to list them in the discovery engine.
• User Control: Instant status toggles to manage platform access.

---

📐 System Design & Data Architecture

ADHYA's architecture follows a classic decoupled full-stack paradigm, utilizing a client-server architecture with persistent data caching and bidirectional socket connections:

graph TD
    subgraph Client Tier [Client Tier React & Vite]
        React[React Client App]
        Axios[Axios Interceptors]
        WS_Client[WebSocket Client]
    end

    subgraph Service Tier [Service Tier FastAPI Web App]
        FastAPI[FastAPI Gateway]
        Auth[OAuth2 JWT Auth Router]
        Admin[Admin Analytics Hub]
        BookingSvc[Booking Handler]
        WS_Svc[WebSocket Connection Manager]
    end

    subgraph Data Tier [Data Database Engine]
        SQLA[SQLAlchemy ORM]
        PG[(PostgreSQL Database)]
    end

    %% Client Interactions
    React -->|User Interactions| Axios
    React -->|Real-time Events| WS_Client
    
    %% API Interactions
    Axios -->|HTTPS / REST API| FastAPI
    WS_Client -->|ws:// WebSockets| WS_Svc
    
    %% Service Internal
    FastAPI --> Auth
    FastAPI --> Admin
    FastAPI --> BookingSvc
    
    %% Database Connection
    Auth --> SQLA
    Admin --> SQLA
    BookingSvc --> SQLA
    WS_Svc -->|run_in_threadpool| SQLA
    SQLA -->|Database Sessions| PG

Loading

1. Database Schema & Relational Design

The database structure is designed to enforce domain boundaries and ensure strict audit logs for billing and booking transactions:

erDiagram
    users {
        int id PK
        string email UK
        string password
        string role
        boolean is_verified
        string interview_status
        datetime created_at
    }
    teacher_profiles {
        int id PK
        int user_id FK
        string full_name
        string subject
        text bio
        int experience_years
        int monthly_rate
        string profile_picture
        string city
    }
    student_profiles {
        int id PK
        int user_id FK
        string full_name
        string grade_class
        string city
        string profile_picture
    }
    teacher_availability {
        int id PK
        int teacher_id FK
        string month_year
        string time_slot
        boolean is_active
    }
    bookings {
        int id PK
        int student_id FK
        int teacher_id FK
        string subject
        string month_year
        string time_slot
        string status
        datetime created_at
    }
    conversations {
        int id PK
        int student_id FK
        int tutor_id FK
        string status
        datetime created_at
    }
    chat_messages {
        int id PK
        int conversation_id FK
        int sender_id FK
        text content
        datetime timestamp
    }
    reviews {
        int id PK
        int student_id FK
        int teacher_id FK
        int booking_id FK
        int rating
        string comment
        datetime created_at
    }
    achievements {
        int id PK
        string student_name
        string score
        string subject
        string detail
        int teacher_id FK
        string color_theme
        boolean is_featured
        datetime created_at
    }

    users ||--o| teacher_profiles : "has profile"
    users ||--o| student_profiles : "has profile"
    users ||--o{ teacher_availability : "provides"
    users ||--o{ bookings : "creates/handles"
    users ||--o{ conversations : "participates"
    conversations ||--|{ chat_messages : "contains"
    bookings ||--o| reviews : "receives rating"
    users ||--o{ achievements : "mentored"

Loading

• User Profiles Split: A single users entity contains authorization credentials and platform roles. Mentors and Students populate distinct profiles (teacher_profiles, student_profiles) linked via 1-to-1 relationships to preserve clean schema attributes.
• Booking-Gated Review Engine: A Review record cannot exist without a reference to a valid Booking. This database constraint prevents spam, verifying that feedback can only be posted by a student who booked the tutor.
• Availability Slot Triggers: When a booking is marked accepted, availability checks dynamically label corresponding time slots as is_booked for other students.

2. Authorization & Session Lifecycle

• Stateless JWT Authentication: Passwords are encrypted using bcrypt. Login requests yield signed JSON Web Tokens (JWT) containing token validity constraints and user roles.
• Route-Level Guards: FastAPI dependency injection evaluates security tokens for each restricted endpoint. Roles are validated at the route boundary, preventing students from accessing mentor statistics or modification routes.
• Axios Interceptors: The client application implements request interceptors to automatically insert the authentication token (Authorization: Bearer <token>) and response interceptors to catch 401 Unauthorized errors, automatically wiping local storage and redirecting expired sessions to the login page.

3. Concurrency & Event Loop Performance

FastAPI executes operations asynchronously. However, standard SQL query execution via SQLAlchemy can block the system's asynchronous event loop.

• ThreadPool Delegation: During real-time WebSocket communication, database read/writes are wrapped inside run_in_threadpool execution blocks. This offloads blocking database operations to worker threads, ensuring the WebSocket gateway can scale and handle active connections simultaneously.
• Connection Pool Pre-Pings: The system configures the SQLAlchemy engine with pool_pre_ping=True to proactively test database connections before allocating sessions, preventing crash exceptions during long-running background tasks.

---

💬 Real-Time Gatekeeper Chat Engine

ADHYA implements a WebSocket connection manager with an active, permission-gated chat cycle:

1. First Inquiry: Students are allowed to send an initial message to a verified tutor.
2. Gatekeeping: Once the inquiry is sent, the conversation status changes to pending and subsequent student messages are locked.
3. Unlock Trigger: The chat unlocks to active immediately when either:
   • The mentor sends a reply back.
   • An active session booking is accepted by the tutor.

graph TD
    A[Student starts conversation] -->|First Message| B(Conversation Status: Pending)
    B -->|Student attempts to message again| C[Blocked: Waiting for Tutor Reply]
    B -->|Tutor replies OR Booking is accepted| D(Conversation Status: Active)
    D -->|Bi-directional chat enabled| E[Unrestricted Real-time Messaging]

Loading

---

📂 Project Architecture

ADHYA-FullStack/
├── app/                      # 🐍 FastAPI Backend codebase
│   ├── crud/                 # Database Query Logic (Chat control, etc.)
│   ├── routers/              # Modular API Route Controllers (Auth, Bookings, etc.)
│   ├── database.py           # SQLAlchemy connection & DB session engines
│   ├── main.py               # Main API launch & CORS Configurations
│   ├── models.py             # SQLAlchemy DB schemas
│   ├── oauth2.py             # JWT Token validation middlewares
│   ├── schemas.py            # Pydantic schemas (Serialization & Request Validation)
│   ├── utils.py              # Password hashing & JWT helpers
│   └── seed_admin.py         # Admin bootstrapping seed script
├── front/                    # ⚛️ React & Tailwind v4 Frontend
│   ├── src/
│   │   ├── api/              # Axios core configuration & interceptors
│   │   ├── components/       # Shared UI Components (Hero, Slider, SuccessWall, etc.)
│   │   ├── pages/            # Core views (Dashboards, Chat, Profiles, Auth)
│   │   └── App.jsx           # Main routing & state controller
│   └── package.json          # Node modules, Vite & Tailwind configuration
├── migrations/               # ⚙️ Alembic database migration scripts
├── alembic.ini               # Alembic configuration profile
├── requirements.txt          # Python dependency manifests
└── .env                      # Global environment configurations

---

⚙️ Core Configuration & Environment Variables

Create a file named .env in the root folder. You can configure it as follows:

Environment Variable	Description	Example Value
DATABASE_URL	PostgreSQL connection string	postgresql://postgres:pass@127.0.0.1:5432/tutor_db
SECRET_KEY	Signature key for generating JWT sessions	4f9a2b8e1c3d7f5a...
ALGORITHM	JWT token hashing algorithm	HS256
ACCESS_TOKEN_EXPIRE_MINUTES	Token validity duration	60
ADMIN_EMAIL	Default administrator account email	admin@adhya.com
ADMIN_PASSWORD	Default administrator account password	YourAdminPass

Note: The frontend project folder also contains a local .env defining the backend target: VITE_API_URL=http://127.0.0.1:8000/api.

---

🚀 Setup & Launch Instructions

📥 1. Database Setup

Ensure you have PostgreSQL running. Run the following command in your PostgreSQL terminal/admin dashboard to create the database:

CREATE DATABASE tutor_db;

🐍 2. Run the FastAPI Backend

Open a terminal in the root directory:

# 1. Create a virtual environment
python -m venv venv

# 2. Activate the virtual environment
# On Windows:
.\venv\Scripts\activate
# On Linux/macOS:
source venv/bin/activate

# 3. Install requirements
pip install -r requirements.txt

# 4. Apply Database Migrations (Or let FastAPI auto-generate tables on run)
alembic upgrade head

# 5. Bootstrapping/Seeding the Admin User
python app/seed_admin.py

# 6. Run the FastAPI development server
uvicorn app.main:app --reload

The backend API documentation will be available at http://127.0.0.1:8000/docs.

⚛️ 3. Run the React Frontend

Open another terminal pane in the front/ directory:

# 1. Navigate to the frontend directory
cd front

# 2. Install NPM dependencies
npm install

# 3. Run the Vite development server
npm run dev

The React development interface will be online at http://localhost:5173/.

---

🔌 API & WebSocket Documentation Reference

Auth & User Endpoints

• POST /api/auth/login - Authenticate users and acquire JWT tokens.
• POST /api/users - Create student or teacher profiles.

Discovery & Search

• GET /api/profiles/all - Query verified tutors with flexible filter metrics (subject, min_price, max_price, city, min_experience).
• GET /api/profiles/user/{u_id} - Retrieve a detailed teacher profile.

Availability & Scheduling

• GET /api/profiles/availability/{teacher_id} - Retrieve active time slots for a mentor.
• POST /api/profiles/availability - Set new time slots (Tutors only).
• DELETE /api/profiles/availability/{slot_id} - Delete availability slots.

Booking System

• POST /api/bookings - Submit session hire request.
• GET /api/profiles/bookings - Access incoming hire requests.
• PATCH /api/profiles/bookings/{booking_id} - Accept/reject requests.

Real-Time Chat Gateway (WebSockets)

• Connection Endpoint: ws://127.0.0.1:8000/api/chat/ws/{user_id}
• JSON Payload Format:

  {
    "receiver_id": 10,
    "content": "Hello! I am looking for mathematics guidance."
  }

---

💎 Design and UX Stack (Frontend Highlights)

• Interactive Motion Engine: Powered by framer-motion to produce smooth, non-intrusive micro-animations on cards, buttons, and navigation elements.
• Responsive Sliding Galleries: Integrated swiper to present mentor portfolios, student reviews, and featured subjects.
• Glassmorphic Design Tokens: Custom background colors (#f7fdfd), elegant header components, and high-contrast styling details powered by Tailwind CSS v4.
• Status Management: Active user sessions are securely managed using JWT local storage integrations and live status headers.