Vignette Project

Storyboard-based platform for language documentation, learning, and audio-rich scenario exploration.

API Docs · Getting Started

Vignette is a web platform for storyboard-based language documentation and learning.

It lets users create, explore, and manage linguistic content built around scenarios, thumbnails, audio, and community-oriented features.

• Vignette Project
  • Project Information
  • Overview
  • Goals
  • Technologies
  • Dependencies
  • Structure
  • Links
  • Getting started
    • Prerequisites
    • Back-End
      • Building and launching the application
      • Test backend code
      • Package the backend as a jar file
    • Front-End
      • Install and launch
      • Build
      • Test frontend code
  • Configuration
    • Development profile
    • Production profile
  • Environment variables
    • Required or recommended
    • Production database variables
  • API documentation
    • Local API docs
    • Published API docs
  • Roadmap ideas
  • Contributing
  • Security
  • License
  • Code of Conduct

Project Information

Title	Vignette
Author	Titouan JOHANNY
Published	false
Universities	- Université de Montréal - Avignon Université

Overview

This project aims at creating storyboards for low resource languages, thus supporting language documentation, exploration, and learning through storyboards. It is aimed at teaching the language to children, as well as providing a centralized platform for community sharing and providing tools for linguists.

It was initiated at Université de Montréal in 2026 by Titouan JOHANNY, as a part of the class IFT-3150 under the supervision of Mr. Louis-Edouard LAFONTANT.

Goals

• Provide a clean platform for documenting languages through structured scenarios
• Support storyboard-like navigation through thumbnails and related media
• Enable audio-backed learning and documentation
• Offer a backend API that can serve both the web app and external tooling
• Keep the project maintainable through a split frontend/backend architecture

Technologies

The backend is built in Java with Spring Boot and follows a API REST architecture. The frontend is built with Vite and Vue.js. The API docs is made with Swagger and OpenAPI, and published on Github Pages.

Dependencies

Languages data and metadata are directly imported from Glottolog

Structure

.
├── .github/workflows/       # CI and documentation publication workflows
├── docs/                    # Static API documentation published on GitHub Pages
├── src/                     # Spring Boot backend
│   ├── main/java/org/titiplex/
│   │   ├── api/
│   │   ├── bootstrap/
│   │   ├── config/
│   │   ├── persistence/
│   │   └── service/
│   └── main/resources/
├── vite/                    # Vue frontend
├── pom.xml                  # Maven backend build
└── API_DOCUMENTATION.md     # Notes about API doc generation/publication

Links

• API docs
• Repository
• Project report (in french)

Getting started

Prerequisites

Make sure you have the following installed:

• Java 23
• Maven 3.9+
• Node.js 22+
• npm
• PostgreSQL (only needed for production-like setup)

Back-End

The backend is the API part of the project that powers the web app.

Building and launching the application

# in project root
mvn clean build

# launching the application
mvn spring-boot:run -Dspring-boot.run.profiles=dev

Note: the -Dspring-boot.run.profiles=dev flag is only needed for development.

Backend should start on http://localhost:8081

Dev endpoints :

• Swagger UI: http://localhost:8081/api/docs
• OpenAPI JSON: http://localhost:8081/api/docs/openapi
• H2 console: http://localhost:8081/h2-console

Test backend code

# in project root
mvn clean test

Package the backend as a jar file

mvn clean package
java -jar target/projet-info.jar --spring.profiles.active=dev

Front-End

Install and launch

cd vite # go to the frontend directory
npm install # install the dependencies, skip if already done
npm run dev

Build

npm run build

To preview the production build:

npm run preview

Test frontend code

cd vite
npm install # install the dependencies, skip if already done
npm run test:run # for single run
npm run test # for watch mode
npm run test:coverage # for coverage report

Frontend end to end tests :

cd vite
npm run e2e

# With playwright UI
npm run e2e:ui

Configuration

Development profile

The dev profile is configured for local development with:

• port 8081,
• an H2 file database,
• H2 console enabled,
• multipart upload limits,
• Swagger / OpenAPI enabled.

Production profile

The prod profile is configured for deployment with:

• port from PORT (default 8081),
• PostgreSQL datasource,
• configurable credentials through environment variables.

Environment variables

Required or recommended

APP_JWT_SECRET=change-me
APP_STORAGE_ROOT=./data/storage

Production database variables

DB_URL=jdbc:postgresql://localhost:5432/vignette
DB_USERNAME=your_user
DB_PASSWORD=your_password
PORT=8081

API documentation

The backend uses springdoc-openapi to generate API documentation automatically.

Local API docs

Once the backend is running:

• Swagger UI: http://localhost:8081/api/docs
• OpenAPI JSON: http://localhost:8081/api/docs/openapi

Published API docs

The repository includes a GitHub Actions workflow that:

• builds the backend,
• starts the API,
• exports the OpenAPI spec,
• publishes the docs/ folder to GitHub Pages.

If GitHub Pages is enabled for the repository, the published API documentation is available from the project’s Pages site.

Roadmap ideas

This project can be extended further with:

• richer admin tooling,
• better media management and storage organization,
• stronger access-control modeling,
• improved contributor onboarding,
• Docker-based local setup,
• seeded demo content,

Contributing

Contributions are welcome.

A good contribution flow is:

1. Fork the repository
2. Create a dedicated branch
3. Make focused changes
4. Add or update tests
5. Open a pull request

Security

If you find a vulnerability, please follow the process described in SECURITY.md.

License

This project is distributed under the GPL-3.0 license. See LICENSE for details.

Code of Conduct

A contributor code of conduct can be found in CODE_OF_CONDUCT.md.