Replace placeholder README with proper project documentation
Made-with: Cursor
This commit is contained in:
Talal Sharabi
131
README.md
131
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
|
### Setup
|
||||||
# Step 1: Clone the repository using the project's Git URL.
|
|
||||||
git clone <YOUR_GIT_URL>
|
|
||||||
|
|
||||||
# Step 2: Navigate to the project directory.
|
```bash
|
||||||
cd <YOUR_PROJECT_NAME>
|
# 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.
|
# Install dependencies
|
||||||
npm i
|
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
|
npm run dev
|
||||||
```
|
```
|
||||||
|
|
||||||
**Edit a file directly in GitHub**
|
The app runs on `http://localhost:8080` by default.
|
||||||
|
|
||||||
- Navigate to the desired file(s).
|
### Environment Variables
|
||||||
- Click the "Edit" button (pencil icon) at the top right of the file view.
|
|
||||||
- Make your changes and commit the changes.
|
|
||||||
|
|
||||||
**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.
|
### Scripts
|
||||||
- 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.
|
|
||||||
|
|
||||||
## 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
|
All project documentation is in the `docs/` folder:
|
||||||
- TypeScript
|
|
||||||
- React
|
|
||||||
- shadcn-ui
|
|
||||||
- Tailwind CSS
|
|
||||||
|
|
||||||
## 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.
|
||||||
|
|||||||
Reference in New Issue
Block a user