Teaching evaluation platform built for the EPF engineering school.
OcéEns II lets program managers, facilitators, campus management and administrators create and run evaluation surveys for EPF's programs, and lets students answer them. Answers can be exported, visualised, and summarised through an LLM. The interface follows EPF's official visual identity.
The application itself is in French: its pages, its seeded demo content and the survey
questions are written in French. The documentation is in English — see GLOSSARY.md for
where that boundary sits.
| Component | Technology |
|---|---|
| Framework | FastAPI (Python 3.12) |
| Authentication | Microsoft Entra ID (Azure AD) via OAuth2.0 / MSAL, Microsoft Graph — or a dev sign-in, see below |
| Database | SQLite (via SQLAlchemy + SQLModel) |
| Templating | Jinja2 (server-side rendering) |
| Frontend | HTML / CSS / JavaScript, no framework |
| Server | Uvicorn |
| Logging | Standard Python logging, through the Uvicorn handlers |
| Exports | Pandas (CSV) |
| Verbatim summaries | Separate daemon calling an LLM (requests-cache, markdown-it-py) |
student: answers the surveys they are invited to.program_manager:<code>: manages the surveys of their program(s).facilitator:<code>: runs the surveys of their program(s).campus_manager:<campus>: campus-wide scope.admin: general administration.
A user can hold several roles, each with its own scope (program codes or campuses
separated by ;). The scope is stored inside the role string itself, after the colon.
The application starts with no Azure application and no LLM key: .env.example ships
AUTH_MODE=dev, which replaces Microsoft Entra ID with a local sign-in page.
- uv — it installs Python 3.12 itself if the machine has no such interpreter
- A
.envfile, copied from.env.example(see Configuration)
cp .env.example .env
docker compose up --buildThe application listens on http://localhost:8000. Without a .env, docker compose
fails with env file .env not found: copying .env.example is the first command of a
fresh clone. The image starts the application alone: for summaries to be written, set
RUN_SUMMARIES_DAEMON=1 in the .env (see Configuration).
The SQLite database is persisted in a directory of the host, mounted into the container:
./database/ by default, or the directory named by LOCAL_DATABASE_DIR.
LOCAL_DATABASE_DIR=/path/to/databaseTo stop and clean up:
docker compose downThe image runs the
oceensentry point without--reload, and the source code is copied into the image rather than mounted: a code change needs adocker compose up --build. For a reload loop, run the application directly (below).The
.envfile is never copied into the image — Compose passes it throughenv_file.
-
Clone the project
git clone <repository-url> cd OceENS
-
Copy the configuration
cp .env.example .env # Windows (PowerShell): Copy-Item .env.example .env -
Install the dependencies with uv, the same command on every system:
uv sync
uv synccreates.venv, installs the versions pinned inuv.lockand theoceenspackage itself, and fetches the Python of.python-version(3.12) if the machine has no such interpreter. Nothing needs to be activated:uv runuses that environment. -
Start the application:
uv run oceens
Or with reload while developing:
uv run uvicorn oceens.main:app --reload
The working directory no longer matters: the templates, the static files and the seed CSV files are installed with the package and found next to it. The exception is the SQLite database, which defaults to
database/at the repository root — setLOCAL_DATABASE_DIRto fix it somewhere else. -
Open http://localhost:8000.
-
(Optional) Start the LLM summaries daemon:
uv run oceens-summaries
This process loops, writes to the database and calls an external LLM service: start it only when summaries are needed. Setting
RUN_SUMMARIES_DAEMON=1in the.envmakes the application start it as a child process on startup and stop it on shutdown: see Configuration for when to set it. In production without Docker,launch.shstarts the application and the daemon in two separatescreensessions.
On every start, the application creates the missing tables, adds the columns missing from
already-deployed tables, and seeds what must always be present: the programs (from
src/oceens/seed_data/Program_list.csv), the default LLM provider, the exchange rate and
the model price list. All of this is idempotent.
On an empty database only, it also inserts a demo dataset: users, surveys, modules,
respondents and answers, so that every screen has something to show. Four surveys are
seeded — three open, one closed with results (MDID5, Troyes campus).
The dataset includes three single-role users, each holding exactly one scoped role. Like the rest of the demo dataset they are seeded on an empty database only: a scoped role is a real permission over a real program, not something to hand out to a database already in service.
| Role | |
|---|---|
oceens.facilitator@epf.fr |
facilitator:MDAI5 |
oceens.program.manager@epf.fr |
program_manager:MDAI5 |
oceens.campus.manager@epf.fr |
campus_manager:Troyes |
Each scope matches a seeded survey, so signing in as any of them shows a populated
dashboard. The other demo users antoine.gademer@epf.fr (user 1) and
yassine.gharbi@epfedu.fr (user 6) combine admin with a business role; the seeded
students hold no role at all.
If you deployed a build between #84 and #38, that version seeded the three addresses above into a populated database too. Anyone signing in with one of them inherits the scope. Check the
usersandrolestables and delete those rows if they are there.
To work on a fork without an Azure application, the dev sign-in lets anyone sign in as any user, without proof of identity. It must never be used in production.
It is turned on by AUTH_MODE=dev, and shaped by DEV_LOGIN_KEY, SECRET_KEY and
ALLOWED_DOMAINS — all four described in Configuration. In dev mode,
the ENTRA_* variables are not needed.
In dev mode the session cookie is no longer restricted to HTTPS (http://localhost
works), /login redirects to /dev/login, /auth/callback does not exist and /logout
clears the session then returns to /. A warning is logged at startup. A red,
non-dismissable banner is shown at the top of every page that includes the shared header:
it recalls the signed-in address, offers Changer d'utilisateur (/dev/login) and says
accès ouvert à tous when DEV_LOGIN_KEY is unset.
POST /dev/login expects a form with email, name (optional) and key (when
DEV_LOGIN_KEY is set). The user is fetched or created exactly as on return from Entra:
an unknown mail becomes a new student. Without name, the displayed name is derived from
the mail (bob.leponge@epfedu.fr → "Bob Leponge"). A new sign-in replaces the session —
that is how you switch user.
In a browser, GET /dev/login lists the users of the database, grouped by role name
without its scope (a user with no role appears under student, a user with several roles
under each of them). Clicking one signs in as them; a free-text field accepts any other
address, with an optional name. When DEV_LOGIN_KEY is set, a single key field appears
and serves every sign-in on the page; the key is never stored in the session.
AUTH_MODE=dev DEV_LOGIN_KEY=my-key uv run oceens
# Sign in as the seeded admin; -c saves the session cookie
curl -i -c cookies.txt \
-d email=antoine.gademer@epf.fr -d key=my-key \
http://localhost:8000/dev/login
# Reuse the cookie (-b) for the following requests
curl -b cookies.txt -c cookies.txt -L http://localhost:8000/Warning
dev mode does not require SECRET_KEY. Without it the key is random and unknown; but
if a known SECRET_KEY is set (shared, copied from an example…), anyone who knows it
can forge a session cookie and bypass DEV_LOGIN_KEY. dev mode accepts that, because
it is only ever meant to run locally.
Without SECRET_KEY, the key is random per process. So every deploy and every restart
signs every user out, and two instances or workers reject each other's sessions. Setting
SECRET_KEY removes it.
With AUTH_MODE unset or entra, sign-in goes through Microsoft Entra ID using MSAL:
1. The user clicks "Se connecter"
→ FastAPI generates a random state (UUID, CSRF protection)
→ Redirect to the Microsoft sign-in page
2. The user authenticates with Microsoft
→ Microsoft redirects to /auth/callback with a code + state
3. The server exchanges the code for an access token
→ Fetches the user's profile through Microsoft Graph
→ Reads the roles and their scopes from the database
→ Creates the session {name, email, roles}
→ Redirects to the matching dashboard
4. On sign-out (/logout)
→ Session and cookies are cleared
→ Sign-out on the Microsoft side
→ Back to the home page
Authentication alone authorises no business action: every route then checks the role and
its scope (program or campus) through require_roles() and the associated helpers.
Copy .env.example to .env and fill it in. That file is the reference: it lists every
variable the code reads, with its default.
| Variable | Required | Meaning |
|---|---|---|
AUTH_MODE |
no (default entra) |
entra or dev, case- and space-insensitive. Any other value: the application logs a critical error and exits with code 1. |
DEV_LOGIN_KEY |
no | Key required by the dev sign-in (form field key), otherwise 401. Empty: sign-in is open. Ignored, with a warning, in entra. |
ALLOWED_DOMAINS |
no | Comma-separated mail domains allowed to sign in (403 for any other), in dev as in entra. Defaults to epf.fr,epfedu.fr in dev, to empty in entra. |
SECRET_KEY |
in entra |
Signs the session cookies. In dev, optional: when missing, a random key is drawn at each start, with a warning, and sessions are lost on restart. |
ENTRA_CLIENT_ID |
in entra |
Azure application ID. |
ENTRA_CLIENT_SECRET |
in entra |
Azure application secret. |
ENTRA_TENANT_ID |
in entra |
Azure tenant (organisation) ID. |
REDIRECT_URI |
no (default https://localhost/auth/callback) |
Callback URL registered in Azure. |
LOCAL_DATABASE_DIR |
no (default database/) |
Directory holding db_oceens.db. A relative path is resolved from the repository root. With Docker Compose, the host directory mounted into the container. |
LLM_API_KEY |
no | Key of the default LLM provider. Empty: the application starts, but requested summaries are marked as configuration errors. |
DEFAULT_PROVIDER_API_TYPE |
no (default ollama) |
API type of the default provider, seeded when the database does not have it yet: ollama, openai or anthropic. |
DEFAULT_PROVIDER_BASE_URL |
no (default https://locallm.mde.epf.fr/ollama) |
Base URL of the default provider's API. |
DEFAULT_PROVIDER_MODEL |
no (default gemma4:26b) |
Model the default provider uses. |
DEFAULT_PROVIDER_KEY_ENV |
no (default LLM_API_KEY) |
Name of the variable holding the default provider's key, not the key itself. Must start with LLM_ or end with _API_KEY. |
RUN_SUMMARIES_DAEMON |
no | 1/true/yes/on starts the summaries daemon alongside Uvicorn. Set it whenever the application is the only process that runs, as with the image or Docker Compose: otherwise requested summaries stay pending, with no error to say so. Leave it unset where something else starts oceens-summaries, as launch.sh does, or two daemons run. |
FORWARDED_ALLOW_IPS |
behind a proxy that ends TLS | Comma-separated addresses of the proxies whose X-Forwarded-Proto and X-Forwarded-For Uvicorn believes, or * for any. Defaults to 127.0.0.1. Behind a proxy that ends TLS, set it to that proxy's address as the application sees it: otherwise the application builds its links with http, and the browser blocks the pages' CSS as mixed content. The Docker image sets *, since its proxy's address is only known at deploy time (on Azure App Service, it is not fixed); set the proxy's address instead where you know it. |
SECRET_KEY signs the session cookies: anyone who knows it can forge an admin session. It
is required unless AUTH_MODE=dev: when missing or empty, the application logs a
critical error and exits at startup (exit code 1). Generate one with
python -c "import secrets; print(secrets.token_urlsafe(32))".
Caution
Never commit the .env file. It is already listed in .gitignore, as are the *.db
files (database/db_oceens.db, cache_llm.db).
Pages and forms are server-rendered; the /api routes are called by the templates, by
fetch() or by a form post.
| Route | Description |
|---|---|
GET / |
Home page, authentication hub. |
GET /login, GET /auth/callback, GET /logout |
Microsoft Entra ID flow. In dev mode, /login redirects to /dev/login and /auth/callback does not exist. |
GET/POST /dev/login |
Dev sign-in: user list in GET, sign-in in POST (only with AUTH_MODE=dev). |
GET /dashboard/student |
Student dashboard. |
GET /dashboard/program-manager |
Program manager dashboard. |
GET /dashboard/facilitator |
Facilitator dashboard. |
GET /dashboard/campus-manager |
Campus management dashboard. |
GET /dashboard/teachers/analytics |
Satisfaction score per teacher, filterable by year / semester / program / teacher. Open to campus_manager and program_manager, each within their own scope. |
GET /dashboard/admin |
Administrator dashboard. |
GET /dashboard/survey-create |
Survey creation / setup. |
| Route | Description |
|---|---|
POST /api/surveys |
Creates a survey. |
GET /api/surveys/{survey_id} |
The questionnaire itself. |
POST /api/surveys/{survey_id} |
Submits the answers. |
POST /api/surveys/{survey_id}/status |
Changes the status of a survey. |
DELETE/POST /api/surveys/{survey_id}/delete |
Deletes a survey. |
GET/POST/DELETE /api/surveys/{survey_id}/students |
Students invited to a survey. |
GET /api/surveys/{survey_id}/export |
CSV export of the answers. |
GET /api/surveys/{survey_id}/visualisation |
Visualisation of the answers. Accepts ?teacher=<name> to open already filtered on a teacher. |
POST /api/surveys/{survey_id}/generate-summaries |
Requests the LLM summaries. |
POST /api/surveys/{survey_id}/destroy-summaries |
Deletes the generated summaries. |
GET /api/surveys/{survey_id}/cost |
Summary cost of that survey. |
| Route | Description |
|---|---|
POST /api/users |
Creates a user from a mail address (admin). |
PUT /api/users/{user_id}/role |
Changes the role of a user. |
GET /backend/prompts, /backend/prompts/new, /backend/prompts/{id}/edit |
LLM prompt screens (admin only). |
POST /api/prompts, PUT/DELETE /api/prompts/{id} |
Prompt CRUD. Editing and deleting are refused while the prompt is referenced in summaries. |
GET /backend/templates |
Survey templates. |
POST /api/templates, PUT/DELETE /api/templates/{id}, POST /api/templates/{id}/toggle-active, POST /api/templates/{id}/duplicate |
Survey template administration. |
POST/PUT/DELETE /api/sections, /api/sections/{id} |
Section administration. |
POST/PUT/DELETE /api/questions, /api/questions/{id} |
Question administration. |
GET /backend/providers and /new, /{id}/edit, /{id}/test; POST /backend/providers/create, /{id}/update, /{id}/delete |
LLM providers (admin). |
GET /backend/llm/prices; POST /backend/llm/settings/rate, /backend/llm/prices/save, /backend/llm/prices/{id}/delete |
Price list and exchange rate. |
GET /backend/llm/costs |
Global summary cost. |
Any 404 other than on / is redirected to / by an HTTP middleware, which then routes
to the right dashboard.
Verbatim summaries are generated by an LLM. The provider is configurable from the
interface (/backend/providers, admin only), without touching the code. The default
provider, Ollama EPF, is created automatically on the first start. It points to the
school's LLM (https://locallm.mde.epf.fr/ollama) unless the DEFAULT_PROVIDER_*
settings describe another one (see Configuration). Changing them later
does not touch the existing row: edit it in /backend/providers. At every start, a default
provider whose API type or key variable name a call would refuse is logged as a warning.
api_type |
Covers |
|---|---|
ollama |
Ollama servers (local, EPF, third-party) |
openai |
OpenAI and any OpenAI-compatible endpoint: vLLM, Groq, Mistral, LM Studio… |
anthropic |
Claude API (Anthropic) |
The SQLite database is not encrypted and ends up in backups. No API key is stored in
it. The llm_providers table only holds the name of the environment variable
(api_key_env, e.g. OPENAI_API_KEY); the value stays in the .env and is resolved only
at call time. That name is validated against an allow-list (LLM_* or *_API_KEY) so it
cannot point at a system secret (SECRET_KEY, ENTRA_CLIENT_SECRET…).
-
Add the key to the
.envwith a conforming name (LLM_*or*_API_KEY):OPENAI_API_KEY=sk-...
-
Restart the summaries daemon (the
.envis read at startup only):uv run oceens-summaries
-
Create the provider in
/backend/providers→ + Nouveau fournisseur: name, API type, base URL, environment variable name (OPENAI_API_KEY) and a default model. The key present / absent indicator confirms the variable is loaded. The Tester button checks that the URL and the key answer, then sends a one-token generation to confirm the account can actually generate (see below). -
Attach a prompt to the provider: in
/backend/prompts, a<select>picks the provider of a prompt. A prompt without a provider (provider_idNULL) falls back to Ollama EPF.
Note
A provider referenced by at least one prompt cannot be deleted (it would break the configuration of those prompts).
Every provider reports its failures in its own format: an exhausted credit is a
429 insufficient_quota at OpenAI, but a 400 "Your credit balance is too low" at
Anthropic. oceens.services.llm_client normalises those answers into categories (quota,
rate_limit, auth, model, server) and derives a readable message from them:
⚠️ Crédit ou quota épuisé chez le fournisseur : la clé est valide mais le compte ne peut plus générer. Rechargez le compte ou choisissez un autre fournisseur. (fournisseur OpenAI, modèle gpt-4o-mini, HTTP 429)
That message is written to Summary.metadata_text in place of the raw JSON — so it is
visible straight from the interface when a summary fails. The provider's raw answer stays
in the daemon logs for diagnosis.
Important
The Tester button does not merely list the models: at OpenAI as at Anthropic,
GET /v1/models still answers perfectly with a zero balance. A one-token generation
ping (negligible cost) is therefore sent afterwards — it is the only way to spot an
exhausted credit before launching a summary campaign.
The cost of each summary is measured, not estimated. At generation time the daemon
records the token counters returned by the provider (Summary.input_tokens,
output_tokens, model_used): that is the only chance to capture them, no API lets you
ask for them afterwards. The amount is then obtained by crossing those counters with the
price list.
Prices live in the database (table llm_model_prices) in euros, and are editable from
the administration: no release is needed to follow a price revision, nor to cover a
locally added provider.
Two components add up:
- a flat cost per generation (
flat_cost_min,flat_cost_max), for a model whose cost is not per token; - a price per million tokens, in and out.
Pre-filled at startup (seed_model_prices, idempotent — a price corrected by hand is
never rewritten):
| Model | Flat cost per generation | In €/M | Out €/M |
|---|---|---|---|
gemma4:26b (Ollama EPF, self-hosted) |
0.02 – 0.05 € | 0.00 | 0.00 |
claude-opus-5 |
— | 4.60 | 23.00 |
claude-sonnet-5 |
— | 2.76 | 13.80 |
claude-haiku-4-5 |
— | 0.92 | 4.60 |
The school's LLM is not free: self-hosted does not mean costless. GPU, electricity and hardware amortisation come to 2–5 cents per summary, all included — hence a flat range rather than a per-token price.
Anthropic publishes in dollars per million tokens; those prices are converted once, at the
usd_to_eur rate stored in settings (0.92 by default, editable in the administration
alongside the price list). The rate only applies at entry: changing it later does not
rewrite existing prices, so a price already applied to past summaries never changes
retroactively.
Other providers' prices (OpenAI, Mistral, Groq…) are left to be entered: they are not guessed. A provider-specific price wins over a generic price for the same model name.
| Where | What |
|---|---|
/backend/llm/costs |
Global cost, broken down by survey and by model (admin) |
| The 💰 button on a survey row | Summary cost of that survey |
A summary cannot be priced when its counters are missing (generated before this feature, or a provider that does not expose them) or when its model has no recorded price. It is then counted separately, never estimated nor flattened to zero: an invented amount would be more harmful than a missing one, since it would be displayed with the authority of a real amount. The screens state explicitly when a total is partial.
Not to be confused with a zero cost: a self-hosted model has a real, small flat cost per generation, which is not the same information as "unknown".
Important
Tracking starts when the feature goes live: summaries generated before it have no counters in the database and cannot be priced retroactively.
Application logs use the standard Python logging module and the uvicorn logger, so
that messages from the application, from auth.py and from seed.py inherit the format,
the colours and the handlers the server already configured.
| Level | Used for |
|---|---|
DEBUG |
Detailed information useful while developing and seeding. |
INFO |
Startup, shutdown and normal application operations. |
WARNING |
An expected resource is missing, or a non-blocking situation. |
ERROR / EXCEPTION |
An operation failed; logger.exception() keeps the traceback. |
CRITICAL |
Missing mandatory configuration, preventing startup. |
Example:
import logging
logger = logging.getLogger("uvicorn")
logger.info("Opération terminée")
try:
operation_risquee()
except Exception:
logger.exception("Échec de l'opération")New diagnostics should use the appropriate logger rather than print(). The application
level is currently set to DEBUG in oceens.core.dependencies. Application logs go through
the Uvicorn handler, usually written to stderr; with separate redirection, use for
instance 2> error.log to collect them.
Everything that Python imports lives under src/oceens/, a single installable package.
The repository root keeps only what is not code: configuration, documentation and the
container files.
OceENS/
├── pyproject.toml # Package metadata, dependencies and entry points
├── uv.lock # Exact resolved versions (committed)
├── .python-version # Python 3.12, picked up by uv
├── launch.sh # Launch script (production, without Docker)
├── Dockerfile # Application image
├── docker-compose.yaml # Service, port, env_file and volumes
├── .dockerignore # Files excluded from the Docker build
├── .env.example # Reference configuration, to copy to .env
├── .env # Environment variables (⚠️ never committed)
├── .gitignore # Files and directories ignored by Git
├── Template_2025.md # Reference wording of the survey template
├── GLOSSARY.md # Domain glossary and language boundary
├── AGENTS.md, CLAUDE.md # Conventions for coding agents
├── tach.toml # The package boundary rule, checked by `tach check`
│
├── .github/workflows/
│ └── architecture.yml # The boundary rule, run on every push and pull request
│
├── scripts/
│ └── check_cycles.py # Rejects import cycles between packages
│
├── docs/
│ ├── smoke-test.md # Manual validation procedure (behaviour is not in CI)
│ ├── adr/ # Architecture decision records
│ └── agents/ # Issue tracker, triage labels, domain docs
│
├── database/ # Database directory (ignored by Git)
│ └── db_oceens.db
│
├── .venv/ # Environment created by uv sync (not committed)
│
└── src/oceens/ # The package — everything below is importable
├── README.md # The package boundary convention, next to the code
├── main.py # FastAPI factory, middlewares and router assembly
├── sondage_loader.py # Loads a full survey for the export
├── survey_loader_from_xlsx.py # Imports surveys from an Excel file
├── summaries_generator_daemon.py # Asynchronous LLM summary processing (separate process)
│
├── core/ # Low-level access and security
│ ├── auth.py # Microsoft Entra ID flow and dev sign-in
│ ├── database.py # SQLite engine, schema migration, SessionDep
│ ├── security.py # Roles, scopes, access control
│ ├── dependencies.py # Shared Jinja templates and logger
│ ├── settings_store.py # Application settings (exchange rate)
│ └── seed.py # Initial data and program synchronisation
│
├── models/ # SQLModel schema, one file per table
│ ├── __init__.py # Re-exports every class (see its docstring)
│ └── User.py, Survey.py, ...
│
├── routers/ # Routes split by business domain
│ ├── pages.py # Home page and dashboards per role
│ ├── surveys.py # Surveys: CRUD, status, export, visualisation
│ ├── students.py # Students invited to a survey
│ ├── users.py # User creation and roles
│ ├── summaries.py # LLM summary triggering
│ ├── prompts.py # Prompt administration
│ ├── survey_templates.py # Survey template administration
│ ├── sections_questions.py # Section and question administration
│ └── llm/ # LLM administration (URLs unchanged)
│ ├── _access.py # Shared access control of the LLM screens
│ ├── providers.py # LLM providers (CRUD + connection test)
│ ├── prices.py # Per-model price list
│ └── costs.py # Global cost and per-survey cost
│
├── services/ # Business logic
│ ├── helpers.py # Navigation, statistics, filters, sorting
│ ├── visualisation_data.py # Aggregations and visualisation context
│ ├── llm_client.py # Multi-provider LLM client (ollama/openai/anthropic)
│ ├── llm_costs.py # Summary cost (measured tokens × price list)
│ └── export_csv.py # CSV export of the answers
│
├── seed_data/ # Seed data read at startup (was import/)
│ ├── Program_list.csv # Programs, synchronised on every start
│ └── seed_answers*.csv # Demo answers of the seeded surveys
│
├── llm_utils/ # LLM tooling outside the application (was llm-utils/)
│ └── README.md # (cost tracking moved into the app, see above)
│
├── templates/ # HTML templates (Jinja2)
│ ├── index.html # Home / sign-in page
│ ├── dev_login.html # Dev sign-in page
│ ├── dashboard/
│ │ ├── admin.html
│ │ ├── student.html
│ │ ├── program_manager.html
│ │ ├── facilitator.html
│ │ ├── campus_manager.html
│ │ ├── teachers-analytics.html # Teacher satisfaction
│ │ ├── survey.html # Answering a survey
│ │ ├── survey_create.html # Survey creation
│ │ └── visualisation.html # Answer visualisation
│ ├── backend/ # Administration pages (admin only)
│ │ ├── prompts.html # LLM prompt list
│ │ ├── prompt_form.html # Shared create/edit form
│ │ ├── templates.html # Survey templates
│ │ └── llm/ # LLM screens (providers, prices, costs)
│ │ ├── providers.html
│ │ ├── provider_form.html
│ │ ├── prices.html # Editable price list
│ │ └── costs.html # Global and per-survey cost
│ └── template_parts/ # Fragments shared between dashboards
│ ├── part_site_header.html
│ ├── part_dashboard_navigation.html
│ ├── part_theme_switcher.html
│ └── ...
│
└── static/
├── css/ # admin.css, student.css, program_manager.css, survey.css,
│ # survey_create.css, visualisation.css, prompt_form.css,
│ # llm_backend.css, theme.css, site_header.css,
│ # dashboard_navigation.css, responsive.css
├── js/
│ └── survey.js
└── img/
/dashboard/teachers/analytics (campus_manager, program_manager) aggregates the
satisfaction score per (teacher, survey) from the QCU_Satisfaction answers that carry
an Answer.teacher (ME sections). The teacher list is sorted with teacher_sort_key(),
case- and accent-insensitive, and stays filterable by school year, semester, program and
teacher.
A client-side selector filters the visualisation without reloading: only the modules of
the chosen teacher stay visible, the Campus and Formation sections being hidden. The page
reads ?teacher=<name> on load to pre-filter itself; links from the analytics screen pass
that parameter, so clicking a teacher's score opens their view directly.
Surveys loaded by oceens.survey_loader_from_xlsx have no QCU_Attendance question:
oceens.services.visualisation_data then uses satisfaction_responses_count as a fallback
denominator for the teacher score. Teacher names are normalised with .title() both at
import and at aggregation, merging case variants ("GADEMER Antoine" and
"Gademer Antoine" = a single entry). Questions are sorted by question_id in the
template, which puts the charts before the verbatims whatever the insertion order.
The campus_manager dashboard only shows closed surveys with at least one respondent. The
questionnaire link and the QR code are hidden there (can_view_survey_link=False): this
role reads results without distributing surveys. The {% if can_view_survey_link | default(true) %} guard leaves the other dashboards unchanged.
When a survey is deleted, students no longer attached to any other survey are deleted
too, to avoid accumulating unused accounts (oceens.services.helpers,
_delete_orphan_students). A safeguard protects users holding a privileged role (admin,
program_manager, facilitator, campus_manager): a teacher or a manager who answered a
survey is never erased.
The Utilisateurs tab of the administrator dashboard offers a + Ajouter un utilisateur
button: a mail is enough to create the account, with the student role by default
(POST /api/users, admin only). The mail is validated (format + allowed domain) and
duplicates are refused.
-
.envcreated with the real Azure credentials and a dedicatedSECRET_KEY(required unlessAUTH_MODE=dev, otherwise the application refuses to start) -
AUTH_MODEunset orentra - Valid SSL certificate (Let's Encrypt or equivalent)
- Behind a proxy that ends TLS:
FORWARDED_ALLOW_IPSset to that proxy (the Docker image sets*), so that pages link their CSS over HTTPS -
https_only=Truein the SessionMiddleware (automatic unlessAUTH_MODE=dev) - Database present (
database/db_oceens.db) or its directory mounted - Environment variables kept secret, including
LLM_API_KEY - Docker Compose:
.envloaded throughenv_file, never copied into the image;LOCAL_DATABASE_DIRpointing at the right directory -
oceens-summariesstarted if LLM summaries are used (seeRUN_SUMMARIES_DAEMON)
.github/workflows/architecture.yml deploys this branch to two environments, staging and
production, each an App Service app on one B1 plan in France Central, always on. Both
hold generated data and no real users, so both sign in through the dev sign-in,
each with its own DEV_LOGIN_KEY and its own SECRET_KEY. That is the one exception to
the deployment checklist's AUTH_MODE line: an environment with
real users signs in through Microsoft Entra ID.
- Staging, on green. A push whose
architecturejob passes is built into one image, tagged with its commit and pushed to GHCR (ghcr.io/epf-mde/oceens:<commit>), then deployed to staging. The image also holds its commit asREVISION, which the application sends back in theX-Revisionheader of every response. The deploy passes only once/dev/loginanswers200with that commit, so a previous container that is still answering does not count. - Production, by promotion only. A run of the workflow started by hand reads the
workflow's push runs on this branch, newest first, and deploys the image of the first
whose
deploy to stagingjob passed to production. It never builds one, so production only ever receives an image whose deploy to staging passed. With no such run, it deploys nothing.
gh workflow run architecture.yml --ref <branch> # promote staging's last green deploy to productionEach environment's settings and secrets live in the GitHub Environment of the same name,
never in a committed file: the variables AZURE_CLIENT_ID, AZURE_TENANT_ID,
AZURE_SUBSCRIPTION_ID, AZURE_RESOURCE_GROUP, AZURE_WEBAPP_NAME, POSTHOG_HOST and
POSTHOG_ENVIRONMENT, and the secrets SECRET_KEY, DEV_LOGIN_KEY and
POSTHOG_PROJECT_TOKEN. Every deploy writes them to the app's settings
(.github/actions/deploy-to-app-service), with AUTH_MODE=dev and
RUN_SUMMARIES_DAEMON=1: the container is the only process, so it starts the summaries
daemon itself. The workflow logs in to Azure through OpenID Connect, as its GitHub
Environment, and stores no Azure password.
- The data is reset at every deploy and at every restart the platform makes. The
SQLite file lives on the container's own disk, not on App Service's lasting storage:
/homeis a network share on which SQLite cannot take its locks, and the summaries daemon writes the same file as the web server. Each start creates the database and seeds it again (What the first start does), so everything written since the last start is lost, cached summaries included. - Without
SECRET_KEY, every deploy signs everyone out (Dev sign-in). Each environment sets its own, never another environment's: anyone who knows it can forge a session cookie and skipDEV_LOGIN_KEY.
The automated tests are still few (uv run pytest), and CI covers the architecture rules
only (.github/workflows/architecture.yml, on every push and pull request), so behaviour
is mostly on you: before proposing a change, run the tests, then the
manual procedure in docs/smoke-test.md: static checks, startup
from a fresh clone, Docker, exit codes on invalid configuration, and the LLM key. Then
test the routes your change touches, on a throwaway SQLite database (never a copy of
production), with the relevant roles and survey statuses.
Two of those static checks are machine-checked architecture rules rather than behaviour:
uv run tach check
uv run python scripts/check_cycles.py
No import may reach past a package's public surface, and no two packages may depend on each other. src/oceens/README.md states the rule and how to write an interface that satisfies it.
- FastAPI
- FastAPI and Uvicorn logging guide
- MSAL Python
- Microsoft Graph
- Jinja2
- SQLAlchemy
- SQLModel
- Pandas
OcéEns team — EPF