How zum-it/vms works
1. What this repo is
- A single-service Java application for a Visitor Management System (VMS).
- The structure is typical of a Spring Boot monolith with layered HTTP, domain, repository, and utility packages.
2. Application entrypoint and runtime
- com.zum.vms.VmsApplication is the bootstrapping class.
- The build is Maven-based (pom.xml, mvnw, Maven wrapper), so the app is designed to run as a packaged Java service.
- Docker support is built in via Dockerfile and docker-compose.yml.
3. Core business model
- The main domain concepts are:
- Company
- Domain
- Office
- These live under model/domain and represent the business data the system manages.
- The overall system name and model suggest these entities form the organizational hierarchy used to manage visitors by company/domain/office context.
4. Persistence boundary
- repository/CompanyRepository, DomainRepository, and OfficeRepository form the data-access layer.
- This is the boundary between the application and the backing database.
- Database initialization is externalized into SQL scripts:
- scripts/01_schema.sql
- scripts/02_data.sql
- That suggests the schema and seed data are provisioned separately from application code.
5. HTTP/API layer
- There are two controller packages:
- ctrl/*Controller.java
- web/*WebController.java
- This strongly suggests two presentation modes:
- one set of controllers for programmatic HTTP access / CRUD endpoints
- one set for browser-facing web pages or server-rendered views
- The split is important for the architecture diagram because it shows the app exposes the same domain through distinct interface layers.
6. Shared CRUD abstraction
- service/CrudController.java appears to be a shared abstraction for controller behavior rather than a classic service implementation.
- That implies controller logic is standardized around CRUD operations and likely reused across the entity-specific controllers.
7. DTO and mapping layer
- The model/dto package contains CompanyDto, DomainDto, OfficeDto, plus Identifiable.
- DTOs indicate the app does not expose domain entities directly everywhere; it has a separate transport shape.
- util/MapperUtils is likely responsible for converting between domain entities and DTOs, which is a key transformation boundary in the request/response flow.
8. Business rules and helper utilities
- util/CompanyUtils and util/PaginationUtils hold reusable domain/helper logic.
- PaginationUtils suggests list endpoints are paginated.
- CompanyUtils likely contains company-specific validation or lookup behavior that is shared across controllers.
9. Error handling
- Two explicit exception types define the main failure modes:
- ResourceAlreadyExists
- ResourceNotFoundException
- This gives the API a clear conflict/not-found boundary for CRUD operations.
- In a diagram, these are downstream from controllers and repositories, used when requested entities cannot be created or retrieved.
10. Web request normalization
- config/TrailingSlashRedirectFilter.java is a request filter that normalizes URLs with trailing slashes.
- This is a small but important HTTP boundary component because it affects how all incoming requests are routed.
11. Configuration and environment
- src/main/resources/application.properties plus environment-specific configs:
- application-test.properties
- application-docker.properties
- vms-config.xml indicates there is also XML-based configuration in the application.
- The repo includes .env, which suggests environment-driven configuration in containerized or deployed runs.
12. Testing and CI/CD
- There is at least one test class: VmsApplicationTests.
- GitHub Actions workflows exist for:
- test.yaml
- docker-deploy.yaml
- So the delivery flow is automated: build/test in CI, then container deploy.
13. Operational artifacts
- manage.sh, start.cmd, and stop.cmd indicate local/runtime lifecycle helpers.
- The presence of Docker Compose plus scripts implies the system can be run both locally and in containerized environments with minimal setup.
14. How the data flows end to end
- A request enters through a controller or web controller.
- The controller uses DTOs and utility mappers to translate input/output.
- It reads or writes entities through the repository layer.
- Repository operations hit the database initialized from SQL scripts.
- Errors are surfaced through the custom exception types, while pagination and trailing-slash handling shape request behavior before/around controller execution.
Main entry points: CompanyController.java API controllers · CompanyWebController.java Web controllers · MapperUtils.java Mapper utils · CompanyRepository.java Company repo
Components 33
Runtime
Application bootstrap, packaging, and deployment artifacts
- VMS app · Bootstraps the Visitor Management System service
src/main/java/com/zum/vms/VmsApplication.java
Presentation
HTTP entrypoints for API and web views
- API controllers · Programmatic CRUD endpoints for core entities
src/main/java/com/zum/vms/ctrl/CompanyController.java - Web controllers · Browser-facing controllers for rendered pages
src/main/java/com/zum/vms/web/CompanyWebController.java - CRUD base · Shared CRUD behavior reused by controllers
src/main/java/com/zum/vms/service/CrudController.java
Domain
Core business entities and transport models
- Company · Top-level organizational entity
src/main/java/com/zum/vms/model/domain/Company.java - Domain · Company-scoped organizational domain
src/main/java/com/zum/vms/model/domain/Domain.java - Office · Physical office or location context
src/main/java/com/zum/vms/model/domain/Office.java - Company DTO · API shape for company data
src/main/java/com/zum/vms/model/dto/CompanyDto.java - Domain DTO · API shape for domain data
src/main/java/com/zum/vms/model/dto/DomainDto.java - Office DTO · API shape for office data
src/main/java/com/zum/vms/model/dto/OfficeDto.java - Identifiable · Shared identity contract for DTOs
src/main/java/com/zum/vms/model/dto/Identifiable.java
Persistence
Repositories and database initialization
- Company repo · Persistence access for companies
src/main/java/com/zum/vms/repository/CompanyRepository.java - Domain repo · Persistence access for domains
src/main/java/com/zum/vms/repository/DomainRepository.java - Office repo · Persistence access for offices
src/main/java/com/zum/vms/repository/OfficeRepository.java - Schema script · Creates database structure
scripts/01_schema.sql - Seed data · Loads initial database rows
scripts/02_data.sql
Support
Shared utilities, filters, configuration, and errors
- Mapper utils · Converts between entities and DTOs
src/main/java/com/zum/vms/util/MapperUtils.java - Company utils · Shared company-specific helper logic
src/main/java/com/zum/vms/util/CompanyUtils.java - Pagination · Shared paging behavior for list endpoints
src/main/java/com/zum/vms/util/PaginationUtils.java - Slash filter · Normalizes trailing-slash requests
src/main/java/com/zum/vms/config/TrailingSlashRedirectFilter.java - Not found · Raised when a resource cannot be located
src/main/java/com/zum/vms/exception/ResourceNotFoundException.java - Already exists · Raised on duplicate resource creation
src/main/java/com/zum/vms/exception/ResourceAlreadyExists.java - App config · Primary application properties
src/main/resources/application.properties - Docker config · Container-specific application properties
src/main/resources/application-docker.properties - Test config · Test-specific application properties
src/main/resources/application-test.properties - XML config · Additional XML-based application configuration
src/main/resources/vms-config.xml
Delivery
Build, test, and operational scripts
- Dockerfile · Builds the application image
Dockerfile - Compose · Container orchestration for local runs
docker-compose.yml - Test workflow · Runs automated build and tests
.github/workflows/test.yaml - Deploy workflow · Builds and deploys container image
.github/workflows/docker-deploy.yaml - Maven wrapper · Maven wrapper entrypoint for builds
mvnw - Maven pom · Defines dependencies and build configuration
pom.xml - Ops scripts · Local start and stop helpers
manage.sh
Connections 41
- VMS app → API controllers: starts · Application exposes API controllers
- VMS app → Web controllers: starts · Application exposes web controllers
- API controllers → CRUD base: uses · Controllers share CRUD behavior
- Web controllers → CRUD base: uses · Web controllers reuse CRUD behavior
- API controllers → Mapper utils: maps · Transforms request and response models
- Web controllers → Mapper utils: maps · Transforms data for views
- API controllers → Company repo: reads/writes · API layer persists company data
- API controllers → Domain repo: reads/writes · API layer persists domain data
- API controllers → Office repo: reads/writes · API layer persists office data
- Web controllers → Company repo: reads/writes · Web layer persists company data
- Web controllers → Domain repo: reads/writes · Web layer persists domain data
- Web controllers → Office repo: reads/writes · Web layer persists office data
- Company repo → Company: stores · Repository manages company entities
- Domain repo → Domain: stores · Repository manages domain entities
- Office repo → Office: stores · Repository manages office entities
- Mapper utils → Company DTO: produces · Maps company entity data to transport shape
- Mapper utils → Domain DTO: produces · Maps domain entity data to transport shape
- Mapper utils → Office DTO: produces · Maps office entity data to transport shape
- Company DTO → Identifiable: implements · DTOs share an identity contract
- Domain DTO → Identifiable: implements · DTOs share an identity contract
- Office DTO → Identifiable: implements · DTOs share an identity contract
- Company utils → Company: supports · Encapsulates company-specific rules
- Pagination → API controllers: supports · Shapes paginated list responses
- Slash filter → API controllers: preprocesses · Normalizes request paths before controller handling
- Slash filter → Web controllers: preprocesses · Normalizes request paths before controller handling
- API controllers → Not found: throws · Missing resources surface as not found
- API controllers → Already exists: throws · Duplicate resources surface as conflicts
- Web controllers → Not found: throws · Missing resources surface as not found
- Web controllers → Already exists: throws · Duplicate resources surface as conflicts
- Schema script → Company repo: supports · Database schema underpins repository access
- Seed data → Company repo: supports · Seeded data underpins repository access
- App config → VMS app: configures · Primary runtime configuration
- Docker config → Compose: configures · Container runtime configuration
- Test config → Test workflow: configures · Test-time application configuration
- XML config → VMS app: configures · Legacy XML configuration used by the app
- Maven pom → Maven wrapper: drives · Maven build is executed through the wrapper
- Maven pom → Dockerfile: builds · Build descriptor feeds container image creation
- Dockerfile → Compose: used by · Compose runs the built image
- Test workflow → Maven pom: uses · CI workflow builds and tests via Maven
- Deploy workflow → Dockerfile: uses · Deploy workflow builds container image
- Ops scripts → Compose: orchestrates · Helper scripts manage local container lifecycle