The codebase is currently in Version 1.0.

This release is stable, but the project is now archived and will no longer receive future updates.

Please use the Prod branch for the latest development state.

The main branch is intended only for stable pushes and snapshots.

This project was developed under a tight timeframe. Some systems and structures were prioritized for functionality over long-term cleanup and refactoring.

Numerosity was built as a demonstration of:

• Java REST technologies
• Vaadin application architecture
• Firebase integration
• educational software design patterns
• full-stack application organization

The platform can still serve as a backend foundation for educational software projects.

However:

• the project is archived
• no future security updates will be provided
• maintainers are responsible for privacy and security compliance if reused

Contributions were previously welcome, but the project is now closed to further development.

Numerosity is a math practice platform built around:

• Vaadin + Spring Boot
• Firebase-backed account/data support
• a lightweight public-facing website

This folder contains the static website for the project.

• Demo questions were generated with LLMs
• Development was accelerated using tools such as:
  • OpenAI Codex
  • GitHub Copilot
  • other open-source tooling

Initial development and architecture were primarily implemented manually.

Numerosity is organized as a full-stack Java application with:

• web UI
• REST endpoints
• backend services
• Firebase integration

Visitor / Student
│
├── Website Landing Page
│   ├── Project Overview
│   └── README Viewer
│
└── Vaadin Application
    ├── MainView
    ├── DashboardView
    └── REST API
        ├── Question Controller
        │   └── QuestionSeeder
        │
        └── User Controller
            └── UserService
                └── UserRepository
                    └── Firestore / Firebase

1. The static site explains the project
2. The Vaadin UI handles interaction
3. REST endpoints expose question/user operations
4. Firebase stores user/application data when configured

The live application code is located under:

server/src/main/java/org/vaadin/numerosity/

The project is split into several logical layers.

• Application.java

  • Spring Boot entry point
  • includes @PWA
  • uses @Theme(variant = "Lumo.dark")

• MainView.java

  • primary landing view
  • top navigation
  • login dialog
  • mode routing

• ui/views/DashboardView.java

  • statistics dashboard
  • performance summaries
  • repository-backed metrics

• rest/QuestionRestController.java
• rest/UserRestController.java
• rest/UserDTO.java

• service/UserService.java
• repository/UserRepository.java
• repository/FsUserRepository.java
• repository/exception/DbException.java

• Subsystems/LoginHandler.java
• Subsystems/QuestionSeeder.java
• Subsystems/QuestionContentLoader.java
• Subsystems/DatabaseHandler.java
• Subsystems/FirebaseHandler.java
• Subsystems/UserManager.java

• Featureset/AppFunctions/bank.java
• Featureset/AppFunctions/rush.java
• Featureset/AppFunctions/zen.java

• Featureset/Supporter/OptionButton.java

Located under:

server/src/test/java/org/vaadin/numerosity/Featureset/MathEngine/

• AlgebraOneTest.java

  • linear functions
  • systems
  • quadratics
  • slopes

• AlgebraTwoTest.java

  • logarithms
  • sequences
  • polynomial evaluation

• CalculusTest.java

  • derivatives
  • integrals
  • Riemann sums
  • limits

• GeometryTest.java

  • area/perimeter
  • polygons
  • triangles

• PrecalculusTest.java

  • trig functions
  • vectors
  • combinatorics

Presentation Layer
│
├── MainView
├── DashboardView
├── Practice Modes
└── Static Website
     │
     ▼
Application Layer
│
├── QuestionRestController
├── UserRestController
└── UserService
     │
     ▼
Core Services
│
├── LoginHandler
├── QuestionSeeder
├── UserManager
└── DatabaseHandler
     │
     ▼
Persistence Layer
│
├── UserRepository
├── FsUserRepository
├── Firestore / Firebase
└── Question JSON Files

1. User opens the website or Vaadin application
2. Frontend routes user to the correct view
3. UI requests data from services
4. Services delegate to repositories/subsystems
5. Firebase is used when credentials exist
6. Demo mode can be used for limited functionality

The backend launches through:

Application.java

Firebase configuration is read from:

server/src/main/resources/application.properties

firebase.project.id=
firebase.credentials.path=
vaadin.launch-browser=true
server.port=${PORT:8080}

This integration has been implemented and tested briefly. To ensure reliability, I would suggest to start with this implementation and build upon it.

The backend supports flexible startup behavior:

• initializes Firebase when credentials exist

• supports fallback/demo operation

• startup handled through:

  • ApplicationConfig
  • FirebaseInitializer

GET /api/questions
GET /api/questions/category/{category}
GET /api/questions/difficulty/{difficulty}
GET /api/questions/random

GET /api/users
POST /api/users

The dashboard tracks:

• total correct answers
• total incorrect answers
• accuracy rate
• streak indicators
• pace metrics
• average answer time
• total answered questions

The application currently exposes three main modes.

MainView
│
├── Bank Mode
│   └── Configurable question sets
│
├── Rush Mode
│   └── Timed answering
│
├── Zen Mode
│   └── Low-pressure practice
│
└── Dashboard
    └── Performance tracking

• configurable sessions
• topic targeting
• structured studying

• speed-focused answering
• live score tracking
• recall training

• relaxed environment
• lower pressure
• reinforcement-oriented

The repository abstraction stores:

• user ID
• username
• correctness counts
• incorrect counts
• performance metrics

Question content is loaded from JSON resources.

server/src/main/resources/data/questions-comprehensive.json
server/Database/Bank/questions.json
server/Database/Bank/questions-comprehensive.json

Question JSON
    │
    ▼
QuestionSeeder

User Action
    │
    ▼
LoginHandler
    │
    ▼
Firebase / Firestore

API Request
    │
    ▼
QuestionRestController
    │
    ▼
QuestionSeeder

Dashboard Request
    │
    ▼
UserService
    │
    ▼
UserRepository
    │
    ▼
FsUserRepository
    │
    ▼
Firebase / Firestore

Serve:

server/website/

Then open:

index.html

The README viewer works best when markdown is served from the same directory.

Run the app from:

server/

using Maven or your IDE.

http://localhost:8080/
http://localhost:8080/dashboard
http://localhost:8080/api/questions
http://localhost:8080/api/users

Configure Firebase credentials and project ID in:

application.properties

If Firebase is missing:

• app may still start
• some persistence features will be unavailable
• demo/fallback behavior may be used

docs/
  API.md
  ARCHITECTURE.md
  SETUP.md

src/
  main/
    java/org/vaadin/numerosity/
      Application.java
      MainView.java
      config/
      entity/
      Featureset/
      repository/
      rest/
      service/
      Subsystems/
      ui/

    resources/
      application.properties
      data/

  test/

website/
  index.html
  styles.css
  script.js
  physics.js
  README.md

target/

• Keep this README aligned with the live server/ codebase
• Prefer documenting implemented behavior over planned behavior
• Update architecture sections when routes/classes change
• Document new website pages/features when added

Numerosity includes:

• a public-facing website
• a Vaadin-based application
• REST APIs
• Firebase-backed persistence

• dashboards
• multiple practice modes
• configurable math practice systems