File size: 3,740 Bytes
1eb23c2
9e42d3b
 
 
 
1eb23c2
9e42d3b
1eb23c2
 
 
9e42d3b
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
---
title: L'Etudiant Admin Dashboard
emoji: 🎓
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

# Admin Dashboard — Getting Started

## Prerequisites

Make sure you have the following installed:

- Python 3.9+
- Node.js 18+
- npm

---

## 1. Start the Backend API (FastAPI)

Open a terminal and run:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
uvicorn backend.app.main:app --reload --host 0.0.0.0 --port 8000
```

Verify it's running:

```bash
curl -s http://localhost:8000/health | jq .
```

---

## 2. Seed the Database

Run the seed script with your CSV file:

```bash
python3 scripts/seed_db.py \
  --db backend/app/db/local.db \
  --csv data/students_base.csv \
  --seed 42 \
  --reset
```

> **Note:** Use an absolute path if you get a `FileNotFoundError`.
> Required CSV columns: `row_id, audience_type, grade, student_subgroup, visited_site, used_ORI, took_test, digital_experience`

Alternatively, seed via the API:

```bash
curl -X POST http://localhost:8000/admin/reset-and-seed \
  -H "Content-Type: application/json" \
  -d '{
    "csv_path": "data/students_base.csv",
    "seed": 42,
    "reset": true
  }'
```

Verify the seed worked:

```bash
curl -s http://localhost:8000/admin/db-stats | jq .
```

---

## 3. Start the Frontend

In a **new terminal** (keep the backend running), start the app from `frontend/`:

```bash
cd frontend
npm install
npm run dev
```

The app will be available at **http://localhost:5173** (or whichever port Vite assigns).

---

## Troubleshooting

**Backend not responding**
- Make sure your virtual environment is activated (`source .venv/bin/activate`)
- Make sure port 8000 is not already in use

**Empty data / blank dashboard**
- The database needs to be seeded before the frontend shows real data
- Run `curl -s http://localhost:8000/admin/db-stats | jq .` to check row counts

**CSV path errors**
- Use an absolute path: `ls -lh /absolute/path/to/students_base.csv`
- Confirm the required column headers are present

---

## API Reference (quick)

| Endpoint | Description |
|---|---|
| `GET /health` | Health check |
| `GET /api/leads?fair_id=1` | List leads |
| `GET /api/leads/{id}` | Lead detail |
| `GET /api/leads/{id}/score` | Lead score |
| `GET /api/kpis/fair/{fair_id}` | Fair KPIs |
| `GET /api/kpis/stands?fair_id=1` | Stand KPIs |
| `GET /api/kpis/conferences?fair_id=1` | Conference KPIs |
| `POST /api/events` | Create event |
| `POST /api/model/recompute` | Recompute scores |
| `GET /api/admin/db-stats` | Database stats |

---

## Deploy on Hugging Face Spaces

This repository is ready to deploy as a **Docker Space** on [Hugging Face Spaces](https://huggingface.co/spaces).

### Quick deploy

1. Go to [huggingface.co/new-space](https://huggingface.co/new-space).
2. Choose **Docker** as the Space SDK.
3. Push this repository (or fork it) to the Space's git remote.
4. The Space will build the Docker image and expose the app at `https://<your-space>.hf.space`.

### Environment variables (optional overrides)

| Variable | Default | Description |
|---|---|---|
| `SEED_ON_STARTUP` | `true` | Seed/reset the DB from CSV on every startup |
| `SEED_CSV_PATH` | `data/students_base.csv` | Path to the CSV file (relative to project root) |
| `SEED_SEED` | `42` | Random seed for deterministic data generation |
| `SEED_RESET` | `true` | Drop and recreate all data before seeding |
| `APP_DB_PATH` | `backend/app/db/local.db` | SQLite database file path |
| `APP_CORS_ALLOW_ORIGINS` | localhost origins | Comma-separated list of allowed CORS origins |

### Local Docker test

```bash
docker build -t letudiant_v3 .
docker run -p 7860:7860 letudiant_v3
# open http://localhost:7860
```