Repository navigation
Architecture
How JobWarden is built: one Spring Boot application split into modules with checked boundaries, the packages every module has, and the conventions the build holds the code to. For using JobWarden, start at Home.
Why it's built this way: the architecture decision records. What's being improved next: the code quality roadmap.
A modular monolith: one Spring Boot application split into Maven modules. The domain modules hold the business logic and know nothing about the web. Two adapter modules expose them: web to the browser, capture to the extension. common holds the little code they all share.
| Module | Responsibility | Depends on |
|---|---|---|
common |
Shared: ErrorCode, the base exceptions, the application logger (JobWardenLogger) and Secrets, which encrypts what the server keeps. No beans, no tables, no business logic |
none |
identity |
Domain: local profiles (users table) |
common |
jobs |
Domain: jobs bookmarked or applied to, with each application's status and event timeline, the reminders set on their calendar and its feed's secret, their fit scores and interview briefs, their salaries compared, their offers' terms and negotiation briefs, and the statistics of how they went | common |
search |
Domain: the Warden Queries (Boolean job-search queries) for Google, LinkedIn, Reddit and X, the description parser that fills in their filters, and the countries of the regions and places postings name; stateless | none |
discover |
Domain: saved searches, the jobs found for them, and the requests the AI Assistant page makes of the assistant |
common, jobs, search
|
market |
Domain: market salaries across countries, from the Stack Overflow survey, Adzuna and Eurostat |
common, jobs
|
cv |
Domain: the profile's CV, as an uploaded file with its text and its preview, as fields to build one from, and rewritten by the assistant for each job; the GitHub repositories its projects come from; each job's cover letter and messages to the people hiring; and the story bank | common |
hiring |
Domain: who's hiring: recruiters, found by the assistant or saved as jobs' contacts, and their posts saying they're hiring |
common, jobs
|
updates |
Domain: the version running, and the latest release on GitHub | common |
database |
Domain: the PostgreSQL login the server connects with: its password, changed in Settings, given to the connection pool at once and, kept encrypted, at the next start; no table | common |
apply |
Domain: auto-apply: the answers application forms ask for, and the jobs queued for the assistant to apply to |
common, jobs
|
inbox |
Domain: recruiters' emails, read from the profile's mailbox over IMAP as often as it says, and offered as updates of its jobs, applied on their own or sorted by the assistant when it says so |
common, jobs, discover
|
watchlist |
Domain: the companies a profile watches, by their job boards on Greenhouse, Lever and Ashby, read every few hours with no AI; the postings that match its saved searches become found jobs |
common, jobs, discover, search
|
web |
Adapter: browser UI. Page controllers, templates, shared layout, Tailwind and HTMX; the CV's and the cover letters' PDFs and the calendar feed |
common, identity, jobs, search, discover, market, cv, hiring, apply, inbox, watchlist, updates, database
|
capture |
Adapter: REST endpoint for the browser extension, and the versions it compares with its own |
common, identity, jobs, updates, apply, cv
|
mcp |
Adapter: the MCP server the AI assistant (Claude Code or Codex) works through, at /mcp
|
common, identity, jobs, search, discover, market, cv, hiring, apply, inbox, watchlist
|
app |
Runnable application and config; wires the modules together | all |
extension/ |
Chrome and Firefox extension (Manifest V3, plain JavaScript); not a Maven module | the capture API |
Every module groups its classes by type, with the same package names everywhere:
| Package | Holds | Where |
|---|---|---|
dto |
Records that carry data: service inputs and outputs, form objects, REST request and response bodies | all modules |
enums |
Enums, e.g. ApplicationStatus, IdentityErrorCode, Language
|
jobs, identity, capture, web
|
service |
Service interfaces | domain modules |
service.impl |
Service implementations (Default*Service) |
domain modules |
entity |
JPA entities | domain modules |
repository |
Spring Data repositories | domain modules |
mapper |
Entity → DTO conversion (*Mapper, static methods) |
domain modules |
exception |
Exceptions the service throws, e.g. ApplicationNotFoundException, and the module's error codes, e.g. JobsErrorCode; in common, ErrorCode, CommonErrorCode and the base exceptions |
domain modules, common
|
logging |
JobWardenLogger |
common |
controller |
Controllers and their exception handlers |
web, capture
|
constants, user
|
Route paths; CurrentUser
|
web |
config |
Spring configuration, e.g. LocaleConfiguration, and the filters every request goes through: RequestIdFilter, SecurityHeadersFilter
|
web |
In the domain modules, dto, enums, service and exception are the public API. Each is marked @NamedInterface in its package-info.java, which tells Spring Modulith that other modules may use it. service uses propagate = false, so service.impl stays internal, as do entity and repository. In common, exception and logging are marked the same way.
Conventions:
-
Null-safety: every package is
@NullMarked(JSpecify) in itspackage-info.java: nothing isnullunless its type says@Nullable. IntelliJ checks it as you type; NullAway checks it as the code compiles, with./mvnw verify -Pnullaway, which CI always runs (it's a profile because Error Prone needs the JVM flags in.mvn/jvm.config, which IntelliJ's own compiler doesn't get). A form field that validation requires is still@Nullable(binding leaves out what a request didn't send): read it with the form'srequired…()method, after validation. A helper that keeps a non-null argument non-null says so with Spring's@Contract("!null -> !null"). A new package needs itspackage-info.java, with@NullMarked. -
Time: "now" comes from the
Clockbean (JobWardenApplication): a class that needs it takes aClockin its constructor and callsInstant.now(this.clock),LocalDate.now(this.clock),this.clock.getZone(), so a test can fix the moment. Entities stamp their own audit times (updatedAt...) with the system's clock. -
Settings: a domain module's settings are one
@ConfigurationPropertiesrecord in itsservice.impl(e.g.WatchlistProperties,jobwarden.watchlist.*), with its defaults (@DefaultValue) and constraints, registered by the module's*Configurationand checked as the app starts. Elsewhere,@Valuegoes on aprivate finalfield, which Lombok copies onto the constructor (lombok.config); never on a setter. -
Records for DTOs: they need no constructors, getters or
equals. Records with more than three fields also get Lombok's@Builder: build them withNewApplication.builder().title(...).build()rather than a constructor call full ofnulls, and leave out the fields that have no value. The records the modules take as input (NewApplication,NewTimelineEvent) check their required fields in their constructor, since a builder can't make sure every required field is set. -
Lombok for entities: only
@Getterand@NoArgsConstructor(access = PROTECTED). Never use@Data,@EqualsAndHashCodeor@ToStringon entities. They trigger lazy loading, and on the two-wayApplicationEntity↔TimelineEventEntitylinktoStringwould recurse forever. -
Package-private controllers and service implementations: only the service interfaces can be called from Java code.
-
Entities never leave their module: services return records, converted with the module's mapper.
-
Errors:
- Services throw the module's own exceptions. Each extends a base class from
common, which decides the HTTP status:NotFoundException(404, one subclass per resource, such asApplicationNotFoundException) orBusinessRuleException(400, thrown as is with the rule's code). - Every exception carries an error code from its module's enum (
IdentityErrorCode,JobsErrorCode), such asJOBS-001. - The exception handlers log each one once, as a warning. Codes only go into ERROR logs, so these lines have none;
capturestill returns the code to the extension. Services don't log the exceptions they throw. - HTMX ignores error responses, so
layout.htmlshows a "That didn't work" banner when an HTMX request fails. - Any other exception is unexpected: a bug or an outage. The handlers log it at ERROR with
COMMON-001and its stack trace, and answer 500 without internal details. Spring MVC's own errors, such as text where a number was expected, keep their usual 4xx status. - In
web,WebExceptionHandlerturns them into an HTTP status, and every error page renders with error.html inside the layout. - In
capture,CaptureExceptionHandlerreturns RFC 9457 problem details (JSON) for the extension, with the code in anerrorCodefield. Every error carries a code, Spring MVC's own ones too:COMMON-002for a malformed request, and validation errors add anerrorsobject (field → message).
- Services throw the module's own exceptions. Each extends a base class from
-
Logging: put Lombok's
@CustomLogon a class (not@Slf4j) to get alogfield of typeJobWardenLogger, set up in lombok.config.debug,infoandwarnare plain SLF4J.erroralso takes an error code as its first argument, and needs one:log.error(JobsErrorCode.SAVE_FAILED, "Could not save application {}", id, exception). The code is added to the message and as a separateerrorCodefield. Each module defines its codes as an enum implementingErrorCodein itsexceptionpackage, prefixed with the module's name (JOBS-001). Levels:- INFO: what changes (created, moved to another status, deleted).
-
DEBUG: reads, rejected forms and captures. Turn it on with
logging.level.com.jobwarden=DEBUG; the line is ready inapplication.properties. - WARN: the modules' own exceptions, logged once by the exception handlers.
- ERROR: only unexpected failures, always with a code.
Log ids, never names or job details.
-
Page controllers are made by composition, not inheritance:
- A controller whose pages render in the layout is a
@PageController. Before each of its handlers,LayoutAdvice(a@ControllerAdvice) puts the selected profile in the model ascurrentProfile, which the header shows, and what the sidebar counts. That's the only time a request looks the profile up. The other controllers (images, downloads, the calendar feed) are plain@Controllers and skip it. - Handlers that need a profile call
requireProfile(model). With no profile selected it throwsProfileNotSelectedException, andWebExceptionHandlersends the browser to/profiles(HTMX requests get anHX-Redirectheader instead of a redirect). -
Pageshas that and the other static helpers,redirectTo(path)andattachment(...), imported statically. What needs a bean is a component the controller takes in its constructor like anything else:FormTexts(an exception's or a form's messages, in the user's language:fieldErrors(result)maps each field to its first validation message),PromptCards(the cards that ask the AI assistant),JobImages(the sites' icons and companies' logos). Optional beans (the runner, the update check) come throughObjectProvider. - Their
@WebMvcTests need@MockitoBeans of whatLayoutAdvicereads:CurrentUser,UserService,ApplicationService,DiscoveryService.WebTestApplicationimports the components.
- A controller whose pages render in the layout is a
-
Constants instead of repeated strings:
-
web'sconstantspackage holds the routes (ControllerConstants), template names (Views), model attribute names (ModelAttributes) and HTMX's headers and events (HtmxHeaders,HtmxEvents). - A form's length limits are constants on the form record (e.g.
NewEventForm.STAGE_LABEL_MAX_LENGTH), and its validation messages use{max}. -
ErrorCode.PROPERTY_NAMEis the one name for the error code, in logs and in error responses.
-
-
Dates and times: a timeline event has a date, and a time of day only when it's known (
LocalDate+LocalTime;DATE+TIMEcolumns). Within a day, events without a time come first. They're wall-clock values, as entered; "now" is taken in the server's time zone, so setTZwhen running in Docker (which defaults to UTC). Moments that are only ever recorded, likecapturedAt, are instants (Instant,TIMESTAMPTZ). The forms have a date field and an optional time field with a Clear time button (a time emptied only in part is invalid, and the browser won't send the form); a form that sends no date, like the status buttons, means now, with the time. The capture API adds the time too, unless the request says"includeTime": false. Display patterns are theformat.dateandformat.dateTimemessages, so each language has its own. -
Entities guard their own rules:
ApplicationEntity.getEvents()is read-only andTimelineEventEntity's constructor is package-private, so events can only be added throughaddEvent, which keeps the status in step with the timeline. -
Formatting: .editorconfig sets tabs for Java and XML plus the import order. In IntelliJ, Code → Reformat Code with Optimize imports applies it. The build checks the imports (Spotless:
java,javax, the rest,org.springframework, then static, none unused) and./mvnw spotless:applyputs them in order. -
The build also stops on an older Java or Maven than the project needs, a dependency declared twice, or a version range (Maven Enforcer), and shows every compiler warning (
-Xlint:all): don't add new ones.
Templates live in web/src/main/resources/templates/<feature>/, and all pages share layout.html. Never name a model attribute application, session or param: Thymeleaf reserves those names, so the template would read something else. HTMX endpoints return a fragment of the page's template, e.g. applications/detail :: application. Pages run under a Content Security Policy (SecurityHeadersFilter): no inline <script>, no onclick= and the like, no hx-on or js: values. Behaviour goes in static/js/app.js, asked for with a data- attribute.
Rules:
- A module's public API is its root package plus the packages marked
@NamedInterface. Everything else is private to that module. Other modules never touch another module's entities or repositories. - Domain modules never depend on the adapters. Business logic belongs in a domain module, never in a controller.
- ModularityTests (Spring Modulith) fails the build if a module uses another module's internals or if module dependencies form a cycle.
-
ConventionsTests (ArchUnit) fails it if the code leaves these conventions: package-private
Default*Serviceimplementations and controllers, records for public DTOs, constructor injection (no setter injection,@Valueonly on final fields), logging throughJobWardenLogger, noSystem.out, no generic exceptions, no transactions in controllers, entities withouttoString/equals/hashCode, exceptions with an error code,java.timeonly, "now" from theClock, and every error code unique and prefixed with its module's name, and every package@NullMarked. - Each module keeps its own Flyway migrations in
src/main/resources/db/migration, namedV<n>__<module>_<description>.sql. Version numbers are shared by all modules: a new migration takes the next free number across the whole project, not just its own module. Hibernate only validates the schema; it never changes it.
JobWarden · Releases · Discord · Suggest a feature · Report a bug · MIT License