labtimesheet/TECH_STACK.md

Lab Timesheet Technology Stack

This document is the team reference for the technologies and development tools used by Lab Timesheet. The five-person development team uses Windows 11 and IntelliJ IDEA. Versions controlled by the repository must not be changed in one developer's environment without a reviewed project-wide update.

1. Architecture

Choice	Use	Rationale
Server-rendered modular monolith	One Spring Boot application organized by account, integration, Project, Task, attendance, notification, and reporting features	A single deployable application keeps transactions, authorization, testing, and deployment manageable for a small team while feature packages preserve clear ownership.
Spring MVC with Thymeleaf	Controllers return HTML pages rendered on the server	The product is a form- and workflow-heavy desktop web application. Server rendering avoids the extra API, SPA state, and authentication complexity of a separate frontend application.
Feature-first Java packages	Each feature owns its controllers, DTOs, entities, repositories, services, and exceptions	Related code stays together, while cross-feature access is limited to public services and DTOs. This supports the five-branch team workflow without duplicating database models.
Executable WAR	Maven packages the application as a WAR that can still run with java -jar	It works with the current Spring Boot deployment while keeping conventional servlet-container compatibility.
HTML sessions and CSRF protection	Spring Security manages authenticated browser sessions	The application is server-rendered. Session cookies and CSRF protection are simpler and safer here than introducing JWTs.

The project deliberately does not use a SPA framework, JWT authentication, microservices, Redis, Kafka, or a generic workflow engine. Those technologies would add operational and development cost without solving a current need.

2. Team workstations

Tool	Team baseline	Use	Rationale
Windows	Windows 11	Team development operating system	One shared OS baseline makes IDE, Docker, path, and command guidance reproducible for the student team.
IntelliJ IDEA	Current supported release	Main IDE for Java, Maven, Spring Boot, Thymeleaf, debugging, and test execution	IntelliJ has strong Spring and Java support and provides one consistent run/debug workflow for the team.
Eclipse Temurin JDK	Java 25	Compile, test, and run the application	Java 25 is the project language baseline, and Temurin matches the JDK distribution used by CI and container builds.
IntelliJ annotation processing	Enabled for the project	Makes Lombok-generated constructors and accessors visible to the IDE	Maven already runs Lombok as an annotation processor. Enabling the same behavior in IntelliJ prevents false editor errors.
Git	Current supported release	Version control and the branch/worktree workflow	Git supports the five persistent feature branches, isolated fix branches, review, and traceable milestone commits.
PowerShell	Included with Windows 11	Run Windows commands and mvnw.cmd	It is available on every team workstation and avoids requiring a separate shell for normal development.
OpenSSL	Current supported release	Generates the Base64 256-bit application master key	A standard cryptographic tool avoids inventing or manually typing security keys. Git for Windows or another trusted Windows package may provide it.
Microsoft Edge or Google Chrome	Current stable release	Manual desktop-browser checks and debugging	The product targets desktop browsers, and both provide standards-based developer tools for HTML, CSS, accessibility, storage, and network inspection.

3. Java and build platform

Technology	Version	Use	Rationale
Java	25	Application language and runtime	Provides a modern supported Java baseline while keeping one version across local development, CI, and production.
Spring Boot	4.1.0	Application framework and dependency management	Supplies compatible Spring modules, production conventions, testing support, and a managed dependency set.
Maven Wrapper	Wrapper 3.3.4; Maven 3.9.16	Java dependency resolution, compilation, tests, Javadoc, and packaging	The checked-in wrapper gives every Windows workstation and CI runner the same Maven version without a separate Maven installation. Use mvnw.cmd on Windows.
Javadoc with doclint	Java 25 toolchain	Validates generated API documentation	Documentation errors are caught during development and CI with the same JDK that compiles the application.
Lombok	Spring Boot-managed version	Removes mechanical constructors and accessors	Targeted Lombok annotations reduce boilerplate while explicit domain constructors, validation, state changes, and entity identity methods remain visible.
Spring Boot configuration processor	Spring Boot-managed version	Generates typed Spring configuration metadata during compilation	It improves configuration accuracy and IntelliJ assistance without adding runtime code.
Embedded/provided Tomcat	Spring Boot-managed version	Servlet runtime for the executable WAR	It is the standard Spring MVC runtime and requires no separate application server for development or the production image.

Unless a row gives an explicit version, Java dependency versions are managed by the Spring Boot 4.1.0 dependency set. This prevents individual libraries from being upgraded into incompatible combinations.

4. Spring and Java dependencies

Dependency	Use	Rationale
Spring Web MVC	Controllers, request binding, validation errors, and server-rendered routes	It matches the Thymeleaf form workflow and keeps browser navigation on the server.
Spring Security	Login, password hashing, sessions, CSRF, role checks, and security headers	Security rules stay in the established Spring filter and authorization model rather than custom code.
Spring Data JPA and Hibernate	Entity mapping, repositories, transactions, optimistic locking, and pessimistic locks	JPA removes routine persistence code while PostgreSQL and Flyway remain the schema authority.
Spring Validation / Jakarta Validation	Request DTO and configuration validation	Validation annotations provide consistent trust-boundary checks and actionable form errors.
Thymeleaf	HTML page and email-template rendering	Templates integrate directly with Spring MVC and work without a client-side framework.
Thymeleaf Spring Security extras	Role- and authentication-aware template rendering	Navigation and controls can reflect server authorization without duplicating role parsing.
Spring Mail	SMTP connectivity and email delivery	Uses the standard Jakarta Mail integration while SMTP settings remain Admin-managed application data.
Spring Boot Actuator	Liveness, readiness, and application health	Standard health endpoints support Docker health checks and production operations.
Spring Boot Flyway integration	Runs reviewed database migrations at startup	Database changes are ordered, repeatable, and validated before Hibernate mappings are used.
Flyway PostgreSQL support	PostgreSQL-specific migration support	The schema uses PostgreSQL features such as btree_gist, checks, partial indexes, and exclusion constraints.
PostgreSQL JDBC driver	Runtime database connection	It is the official Java driver for the selected database.
Spring Boot DevTools	Development-only restart support	Shortens the local feedback loop without becoming a production dependency.
Spring Boot Docker Compose support	Optional runtime integration	It is available for Spring tooling, although the documented development loop currently starts PostgreSQL and Mailpit explicitly.

5. Database and persistence

Technology	Version	Use	Rationale
PostgreSQL	18.4	Development, test, and production database	The domain requires reliable transactions, constraints, date/time types, partial indexes, exclusion constraints, and strong concurrency behavior. Using the same engine everywhere avoids H2-specific surprises.
Flyway	Spring Boot-managed version	Versioned schema migrations	Flyway makes the reviewed SQL schema reproducible on an empty database and safe to validate in CI.
Hibernate schema validation	ddl-auto=validate	Confirms entity mappings match the migrated schema	Hibernate must not silently create or alter production tables; Flyway remains authoritative.
PostgreSQL btree_gist	Database extension	Supports exclusion constraints such as overlapping leave prevention	The database can reject invalid concurrent data even when two application requests race.

6. Frontend stack

Technology	Version	Use	Rationale
Thymeleaf	Spring Boot-managed version	Page layouts, fragments, forms, validation messages, and role-aware navigation	It keeps rendering and authorization close to the Spring MVC application.
HTML5	Browser standard	Semantic forms, tables, native dialogs, and accessible page structure	Native elements reduce custom JavaScript and provide built-in keyboard and form behavior.
Tailwind CSS	4.3.3	Compiled design tokens and utility-based styling	It supports the shared light/dark desktop design without shipping a runtime CSS framework.
Tailwind CLI	4.3.3	Builds the committed production CSS asset	The small CLI is sufficient; no frontend bundler or SPA toolchain is needed.
Lucide Static	1.27.0	Local SVG icon sprite	Icons are available offline, inherit theme color, and do not require React or an icon CDN.
Native JavaScript modules	Browser standard	Small interactions such as theme selection, sidebar state, dialogs, and local search	The current interactions do not justify a client-side application framework.
Node.js	24.x	Frontend build scripts and JavaScript tests	Node 24 is the pinned LTS toolchain used consistently by developers, CI, and the Docker build.
npm	11.x	Reproducible frontend dependency installation	npm ci and the committed lockfile install exactly the reviewed dependency graph.

7. External services and integrations

Service or standard	Use	Rationale
SMTP	Activation, password recovery, and ordinary workflow email	SMTP is widely supported and allows the application to work with university or other approved mail providers. Configuration is tested and activated through the Admin console.
Mailpit	Development SMTP server and web inbox	Mailpit captures messages locally so developers never send test activation or recovery email to real users. The development image is pinned to axllent/mailpit:v1.27.4.
HolidayAPI	Optional Vietnam holiday preview/import	It reduces manual holiday entry while imported dates remain a preview and the Admin's local day-off decision remains authoritative.
AES-256-GCM from the JDK	Encrypts stored SMTP and HolidayAPI secrets	Authenticated encryption protects confidentiality and detects modification without adding another cryptography dependency.
HTTPS reverse proxy	Production TLS termination and forwarding	The application image stays focused on Java while an operator-managed proxy handles certificates and the public HTTPS endpoint.

8. Testing tools

Tool	Use	Rationale
JUnit Jupiter	Unit and integration test framework	It is the standard JUnit 5 programming model supplied by Spring Boot and works with Maven Surefire and IntelliJ.
Maven Surefire	Maven/Spring Boot-managed version	Discovers and runs the Java test suite
Spring Boot Test	Application-context and integration testing	It verifies real Spring configuration, dependency injection, transactions, and profile behavior.
Focused Spring Boot test starters	Data JPA, Flyway, Mail, Security, Thymeleaf, Validation, and Web MVC test support	Each test slice receives the framework support it actually exercises instead of one unrelated test environment.
Spring MVC Test / MockMvc	Controller, security, validation, and Thymeleaf route tests	HTTP behavior can be tested quickly without launching a separate browser process.
Spring Security Test	Authenticated role and CSRF test support	Tests can prove allowed and denied behavior using the same security filter chain.
Mockito	Test doubles for external or out-of-scope collaborators	It isolates a focused unit or MVC slice without replacing the database behavior being tested.
Testcontainers	Spring Boot-managed version	Starts disposable infrastructure for integration tests
Testcontainers PostgreSQL	PostgreSQL 18.4 test container integration	It validates Flyway SQL, JPA mappings, constraints, locking, and concurrency against the production database engine.
Node built-in test runner	Frontend asset and workflow contract tests	The required JavaScript checks run without adding another test framework.
Playwright	Automated desktop-browser end-to-end journeys	Playwright provides repeatable Chromium-based tests for bootstrap, login, role navigation, Projects, Tasks, attendance, and accessibility-sensitive workflows required by the instructor.
Manual Edge/Chrome journeys	Exploratory and final visual checks	Manual checks still catch layout, focus, contrast, and real-browser integration issues that focused automated tests may not explain clearly.
Markdown evidence records	RED/GREEN and affected-suite evidence under docs/tests/	Each feature change remains traceable to requirements, commands, expected results, and test boundaries.

9. Reporting technologies

These tools are approved for the reporting iteration. They must be added with reviewed, pinned versions when their corresponding feature is implemented.

Technology	Approved baseline	Use	Rationale
Chart.js	4.5.1	Meaningful attendance and Project trend charts	It provides accessible, lightweight charts without changing the server-rendered architecture; every chart also requires a text or table alternative.
Apache POI XSSF	Compatible 5.5.x	Excel .xlsx exports	POI is the established Java library for native Excel workbooks and supports typed cells and formatting.
OpenPDF openpdf-html	Compatible 3.0.x	PDF generation from a dedicated print-safe template	It keeps PDF generation inside Java and supports an embedded Unicode font for Vietnamese content.

10. Containers and production delivery

Technology	Version or baseline	Use	Rationale
Docker Desktop	Current supported Windows release using Linux containers	Development infrastructure, Testcontainers, and local production-image checks	It provides the Docker Engine expected by PostgreSQL, Mailpit, Testcontainers, and multi-stage builds on Windows 11.
Docker Compose	v2.20 or newer	Production example with bundled or external PostgreSQL	One documented file supports both deployment topologies while retaining persistent database storage.
Docker BuildKit / Buildx	Current workflow-pinned release	Multi-stage and multi-architecture image builds	Buildx produces native Linux AMD64 and optional ARM64 images with reproducible build stages.
Node Alpine image	Node 24, digest-pinned	Builds Tailwind and Lucide assets	Frontend tools do not remain in the final Java runtime image.
Eclipse Temurin images	Java 25 JDK and JRE, digest-pinned	Builds the WAR and runs the production application	Separate build and runtime images reduce the final image size and match the Java baseline.
PostgreSQL image	18.4, digest-pinned	Optional bundled production database	Digest pinning prevents an image tag from silently changing during deployment.
OCI image registry	Gitea package registry	Stores immutable application images	Commit-SHA tags make a deployed version identifiable and allow a controlled rollback.

The final application container runs as non-root UID/GID 10001, uses a read-only root filesystem in Compose, drops Linux capabilities, and exposes Actuator readiness and liveness checks.

11. Source control and CI/CD

Tool	Use	Rationale
Gitea	Git hosting, review, Actions, and OCI package registry	One project-owned platform stores source, reviews changes, runs checks, and publishes production images.
Gitea Actions	Verification on every pull request and push	CI repeats frontend, Java, PostgreSQL, Javadoc, generated-asset, and whitespace checks outside a developer workstation.
Container workflow	Manual dispatch or main push only	Image builds are expensive and potentially publish artifacts, so they run only after an internal verification job and never for ordinary feature branches or pull requests.
actions/checkout	7.0.1, immutable SHA pin	Checks out source without retaining push credentials
actions/setup-java	5.7.0, immutable SHA pin	Installs Temurin Java 25 and manages the Maven cache
actions/setup-node	7.0.0, immutable SHA pin	Installs Node 24 and manages the npm cache
Docker Buildx action	4.2.0, immutable SHA pin	Prepares multi-architecture image building
Docker Login action	4.6.0, immutable SHA pin	Authenticates only publication jobs to the registry
Docker Build Push action	7.3.0, immutable SHA pin	Builds and publishes OCI images

12. Configuration and source-of-truth files

File	Controls
pom.xml	Java version, Spring Boot version, Java dependencies, packaging, and annotation processors
.mvn/wrapper/maven-wrapper.properties	Maven Wrapper and Maven distribution
package.json and package-lock.json	Node/npm baseline and exact frontend dependencies
src/main/resources/application*.yaml	Shared, development, and production Spring configuration
src/main/resources/db/migration/	Flyway database schema history
Dockerfile	Production multi-stage application image
compose.yaml	Production application and optional PostgreSQL deployment example
.gitea/workflows/	Verification and container publication workflows
DEVELOPMENT.md	Windows/IDE-oriented local setup and run instructions
TESTING.md	Test commands, TDD rules, and evidence format
DEPLOYMENT.md	Production container configuration and operation

When documentation and a build file disagree about an installed version, the build file and lockfile are authoritative. Update this document in the same reviewed change whenever the selected stack changes.