diff --git a/README.md b/README.md
index 70b7c82..6e543eb 100644
--- a/README.md
+++ b/README.md
@@ -1,73 +1,118 @@
-# Welcome to your Lovable project
+# EnCoach — Adaptive Learning Platform (Frontend)
 
-## Project info
+The frontend application for the EnCoach Adaptive Learning Platform, serving UTAS university students and freelance learners across IELTS, Mathematics, and IT courses.
 
-**URL**: https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID
+Built with React 18, TypeScript, and Vite. Connects to an Odoo 19 backend via REST API.
 
-## How can I edit this code?
+## Tech Stack
 
-There are several ways of editing your application.
+| Layer | Technology |
+|---|---|
+| Framework | React 18 + TypeScript |
+| Build | Vite 5 (SWC) |
+| Routing | React Router v6 |
+| State / Data | TanStack Query v5, React Context |
+| UI Components | shadcn/ui + Radix UI |
+| Styling | Tailwind CSS 3 |
+| Forms | react-hook-form + Zod validation |
+| Charts | Recharts |
+| Icons | Lucide React |
 
-**Use Lovable**
+## Architecture
 
-Simply visit the [Lovable Project](https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID) and start prompting.
+```
+src/
+├── components/         # Shared UI, layouts, AI components
+│   ├── ai/             # 14 AI-powered components (coaching, grading, insights)
+│   └── ui/             # shadcn/ui primitives
+├── contexts/           # AuthContext (JWT session management)
+├── hooks/
+│   ├── queries/        # TanStack Query hooks (exams, assignments, LMS, adaptive)
+│   └── usePermissions  # Entity-scoped permission checks
+├── lib/
+│   ├── api-client.ts   # Centralized HTTP client with JWT + 401 interception
+│   └── query-client.ts # TanStack Query configuration
+├── pages/
+│   ├── admin/          # Admin & LMS management (courses, batches, taxonomy, resources)
+│   ├── student/        # Student portal (dashboard, courses, adaptive learning flow)
+│   └── teacher/        # Teacher portal (courses, assignments, attendance, grading)
+├── services/           # 21 API service modules mapped to Odoo endpoints
+└── types/              # 14 TypeScript type definition files
+```
 
-Changes made via Lovable will be committed automatically to this repo.
+## Key Features
 
-**Use your preferred IDE**
+- **7 User Roles** — Student, Teacher, Admin, Corporate, Master Corporate, Agent, Developer
+- **Adaptive Learning Engine** — Diagnostic assessment, proficiency profiling, AI-generated learning plans, topic-level content delivery
+- **LMS Integration** — Course management, batches, timetables, attendance, grades (OpenEduCat via API)
+- **Exam Portal** — IELTS-style exams with AI grading, writing evaluation, speaking assessment
+- **14 AI Components** — Study coach, writing helper, grading assistant, risk detection, insights panel, batch optimizer, report narratives
+- **Entity-Scoped Permissions** — Fine-grained access control with 77+ permission types
+- **Multi-Subject Support** — IELTS (English), Mathematics, IT — all using a universal subject taxonomy
 
-If you want to work locally using your own IDE, you can clone this repo and push changes. Pushed changes will also be reflected in Lovable.
+## Getting Started
 
-The only requirement is having Node.js & npm installed - [install with nvm](https://github.com/nvm-sh/nvm#installing-and-updating)
+### Prerequisites
 
-Follow these steps:
+- Node.js 18+ (or Bun)
+- Odoo 19 backend running (see `docs/ODOO_BACKEND_SRS_v3.md`)
 
-```sh
-# Step 1: Clone the repository using the project's Git URL.
-git clone <YOUR_GIT_URL>
+### Setup
 
-# Step 2: Navigate to the project directory.
-cd <YOUR_PROJECT_NAME>
+```bash
+# Clone the repository
+git clone https://git.albousalh.com/devops/encoach_frontend_new_v1.git
+cd encoach_frontend_new_v1
 
-# Step 3: Install the necessary dependencies.
-npm i
+# Install dependencies
+npm install
 
-# Step 4: Start the development server with auto-reloading and an instant preview.
+# Configure environment
+cp .env.example .env.development
+
+# Start development server
 npm run dev
 ```
 
-**Edit a file directly in GitHub**
+The app runs on `http://localhost:8080` by default.
 
-- Navigate to the desired file(s).
-- Click the "Edit" button (pencil icon) at the top right of the file view.
-- Make your changes and commit the changes.
+### Environment Variables
 
-**Use GitHub Codespaces**
+| Variable | Description | Default |
+|---|---|---|
+| `VITE_API_BASE_URL` | Odoo backend API base URL | `http://localhost:8069/api` |
+| `VITE_APP_NAME` | Application display name | `EnCoach` |
 
-- Navigate to the main page of your repository.
-- Click on the "Code" button (green button) near the top right.
-- Select the "Codespaces" tab.
-- Click on "New codespace" to launch a new Codespace environment.
-- Edit files directly within the Codespace and commit and push your changes once you're done.
+### Scripts
 
-## What technologies are used for this project?
+| Command | Description |
+|---|---|
+| `npm run dev` | Start dev server with HMR |
+| `npm run build` | Production build |
+| `npm run build:dev` | Development build |
+| `npm run preview` | Preview production build |
+| `npm run lint` | Run ESLint |
+| `npm run test` | Run tests |
+| `npm run test:watch` | Run tests in watch mode |
 
-This project is built with:
+## Documentation
 
-- Vite
-- TypeScript
-- React
-- shadcn-ui
-- Tailwind CSS
+All project documentation is in the `docs/` folder:
 
-## How can I deploy this project?
+| Document | Purpose |
+|---|---|
+| `ENCOACH_UNIFIED_SRS.md` | Master Software Requirements Specification |
+| `ODOO_BACKEND_SRS_v3.md` | Backend developer handoff (Odoo modules + API contract) |
+| `ENCOACH_PRODUCT_DESCRIPTION.md` | Non-technical product overview |
+| `UTAS_MASTER_PLAN.md` | Project timeline and milestones |
+| `MATH_IT_ADAPTIVE_LEARNING_SRS.md` | Adaptive learning engine specification |
 
-Simply open [Lovable](https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID) and click on Share -> Publish.
+## Backend API
 
-## Can I connect a custom domain to my Lovable project?
+The frontend expects an Odoo 19 backend exposing REST endpoints under `/api/`. All service modules in `src/services/` map directly to the API contract defined in `docs/ODOO_BACKEND_SRS_v3.md`.
 
-Yes, you can!
+Authentication uses JWT tokens stored in `localStorage`, with automatic 401 interception and redirect to login.
 
-To connect a domain, navigate to Project > Settings > Domains and click Connect Domain.
+## License
 
-Read more here: [Setting up a custom domain](https://docs.lovable.dev/features/custom-domain#custom-domain)
+Proprietary — EnCoach Platform. All rights reserved.