[kaymeer]

ALICE Insights project. This pull request is part of ALICE Insights, a project by students of the Amsterdam University of Applied Sciences (AUAS) for ALICE, with George Raduta as contact. It targets the project's base branch alice-insights/dev, not main. The alice-insights/* branches keep the project team's work separate from regular development.

The generation service that reads these templates is in the private repository FLP-AUAS/ALICE-Insights, in its own pull request. Both pull requests can be reviewed on their own: this one is tested with Bookkeeping's test suites, the other against a fake Bookkeeping.

I DON'T have JIRA ticket

• explain what this PR does
• if it is a new feature, explain how you plan to use it
• tests are added
• documentation was updated or added

What this PR does

Adds presentation templates to Bookkeeping: two tables to store them, a seeder with two examples, and two endpoints to read them. A template is the content of a presentation: a name, a title, a description and an ordered list of content modules, each with its own settings. It holds no styling.

Tables

Table	Columns
templates	id, name (unique), title, description (optional)
template_modules	id, template_id (deleted with its template), position (unique per template, 0 is the first slide), type, title (optional), options (JSON)

A module type names code in the ALICE Insights generation service that turns data into slides. Bookkeeping only stores which modules a template uses, in which order and with which settings. The same module type can appear in several templates, each time with its own title and settings.

Endpoints

Endpoint	Returns
GET /api/templates	All templates sorted by title, with id, name, title and description, without modules. Not paginated, pagination parameters are rejected
GET /api/templates/:templateId	One template with its modules in presentation order, each with position, type, title and options. A 404 names the id, and an id that is not a positive number gets a 400

Both are read endpoints for every signed-in user, like the other read endpoints.

Example templates (seeder)

Template	Modules in order
Run Manager Weekly Report	title slide, fill calendar, fill efficiency, running time, end-of-run reasons
LHC Fill Summary	title slide, fill calendar, fill efficiency

The data modules show PHYSICS runs ({"run_definitions": ["PHYSICS"]}).

Design choices

• Two tables instead of one JSON column. The modules of a template are rows with a position, so a later admin page can add, remove and reorder single modules, and the database guarantees that each position is used once per template.
• No styling in a template. The content of a presentation is kept separate from its design. Colors, fonts and logos are applied when a presentation is generated, so every template gets the same look, and themes can be stored on their own later without changing these tables.
• Example templates in a seeder, not in a migration. As with the other example data of Bookkeeping, the seeder runs for the tests and in development only. The migration creates the tables, so a production database starts empty.
• Read endpoints only. Creating and editing templates is left for an admin page restricted to the admin role, as for tags. The repository already offers the methods it will need.
• Templates are read by id. The caller gets the ids from the list endpoint.

Where to look

The PR has three commits, one per step:

Commit	Layer	Files
1. Tables and example data	Migration	migrations/v1/20261028100000-create-templates.js
	Seeder	seeders/20261028100000-templates.js
	Models	models/template.js, models/templateModule.js, their typedefs, models/index.js
2. Read endpoints	Repository	repositories/TemplateRepository.js
	Adapters	adapters/TemplateAdapter.js, adapters/TemplateModuleAdapter.js
	Service	services/template/TemplateService.js, getAllTemplates.js, getTemplate.js, getTemplateOrFail.js
	DTOs, controller, route	GetAllTemplatesDto.js, GetTemplateDto.js, templates.controller.js, templates.router.js
	Tests	test/api/templates.test.js, test/lib/server/services/template/
3. Documentation	HTTP API documentation	openapi.yaml, with API.md and index.html generated by npm run docs:api

The other changed files are the index.js files that register the new parts. The layers follow the run types endpoints.

How we plan to use it

ALICE Insights builds presentations from Bookkeeping's data. Its generation service reads a template through these endpoints with the user's own token, and builds the presentation from the modules the template lists. A Presentations page in Bookkeeping will list the templates through GET /api/templates so the user can pick one. These parts follow in separate pull requests.

How to try it

• Start Bookkeeping in development, then add the example data: docker compose exec application npm run sequelize -- db:seed:all
• GET /api/templates?token=<token> returns both templates.
• GET /api/templates/1?token=<token> returns the Run Manager Weekly Report with its five modules.
• GET /api/templates/99?token=<token> returns a 404, and GET /api/templates/-1?token=<token> a 400.

Notable changes for users:

• N/A. The endpoints are read by the ALICE Insights generation service.

Notable changes for developers:

• New models Template and TemplateModule, with Template.hasMany(TemplateModule) as modules and TemplateModule.belongsTo(Template).
• New TemplateRepository, TemplateAdapter and TemplateModuleAdapter, and the Template and TemplateModule entities.
• New TemplateService with getAll() and getOneOrFail(id), backed by getAllTemplates, getTemplate and getTemplateOrFail.
• New endpoints GET /api/templates and GET /api/templates/:templateId, with GetAllTemplatesDto and GetTemplateDto, documented in the HTTP API documentation under Templates.
• New seeder 20261028100000-templates.js with two example templates.
• New API tests (templates.test.js) and service tests (TemplateService.test.js). The unit, API and browser suites were run in docker and pass, and so does npm run lint.

Changes made to the database:

• New tables templates and template_modules, created by the migration 20261028100000-create-templates.js. template_modules.template_id references templates.id with ON DELETE CASCADE, and (template_id, position) is unique. No existing table changes.

[codecov]

Codecov Report

❌ Patch coverage is 96.46018% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 46.32%. Comparing base (743fe7f) to head (023056d).

Files with missing lines	Patch %	Lines
...e/migrations/v1/20261028100000-create-templates.js	62.50%	3 Missing ⚠️
lib/server/controllers/templates.controller.js	94.73%	1 Missing ⚠️

Additional details and impacted files

@@                  Coverage Diff                   @@
##           alice-insights/dev    #2308      +/-   ##
======================================================
+ Coverage               46.00%   46.32%   +0.32%     
======================================================
  Files                    1070     1084      +14     
  Lines                   17610    17723     +113     
  Branches                 3261     3266       +5     
======================================================
+ Hits                     8102     8211     +109     
- Misses                   9508     9512       +4     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.