EnCoach Frontend — v2

Branching Workflow

This repo is connected to the staging server via a Git post-receive hook. All deployment is automatic — but only after code review approval.

How to contribute

1. Never push directly to main — branch protection will block it.
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.

---

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

# 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.