Merge feature/full-frontend-v1 into main (initial frontend codebase by Yamen)

Made-with: Cursor
2026-04-01 18:18:52 +04:00
parent b04db0b06c 110a0b7105
commit 41846a6eb6
307 changed files with 46575 additions and 21 deletions
--- a/README.md
+++ b/README.md
@@ -8,20 +8,132 @@ This repo is connected to the staging server via a Git post-receive hook.
 ### How to contribute

 1. Never push directly to `main` — branch protection will block it.
-2. Create a feature or fix branch:
-   ```bash
-   git checkout -b feature/your-feature-name
-   ```
-3. Develop, commit, and push your branch:
-   ```bash
-   git push origin feature/your-feature-name
-   ```
-4. Open a **Pull Request** on Gitea targeting `main`.
-5. Request review from **devops (Talal)**.
-6. Once approved and merged, the staging server rebuilds and redeploys automatically.
+2. Push your changes to your feature branch (e.g. `feature/full-frontend-v1`)
+3. Open a Pull Request on Gitea targeting `main`
+4. Request review from **devops (Talal)**
+5. Once approved and merged, the staging server rebuilds and redeploys automatically.

 ### Environment

 The `.env` file is **not committed**. It lives only on the staging server at `/opt/encoach/frontend-v2/.env`.
-Contact the team lead if you need a local copy of the environment variables.

+---
+
+# EnCoach — Adaptive Learning Platform (Frontend)
+
+The frontend application for the EnCoach Adaptive Learning Platform, serving UTAS university students and freelance learners across IELTS, Mathematics, and IT courses.
+
+Built with React 18, TypeScript, and Vite. Connects to an Odoo 19 backend via REST API.
+
+## Tech Stack
+
+| 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 |
+
+## Architecture
+
+```
+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
+```
+
+## Key Features
+
+- **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
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+ (or Bun)
+- Odoo 19 backend running (see `docs/ODOO_BACKEND_SRS_v3.md`)
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://git.albousalh.com/devops/encoach_frontend_new_v1.git
+cd encoach_frontend_new_v1
+
+# Install dependencies
+npm install
+
+# Configure environment
+cp .env.example .env.development
+
+# Start development server
+npm run dev
+```
+
+The app runs on `http://localhost:8080` by default.
+
+### Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `VITE_API_BASE_URL` | Odoo backend API base URL | `http://localhost:8069/api` |
+| `VITE_APP_NAME` | Application display name | `EnCoach` |
+
+### Scripts
+
+| 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 |
+
+## Documentation
+
+All project documentation is in the `docs/` folder:
+
+| 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 |
+
+## Backend API
+
+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`.
+
+Authentication uses JWT tokens stored in `localStorage`, with automatic 401 interception and redirect to login.
+
+## License
+
+Proprietary — EnCoach Platform. All rights reserved.