Clarify mapping between build modules and deployed services#3086
Open
Senthil455 wants to merge 1 commit into
Open
Clarify mapping between build modules and deployed services#3086Senthil455 wants to merge 1 commit into
Senthil455 wants to merge 1 commit into
Conversation
Add a new section to the architecture documentation that explains the relationship between Nomulus build modules (core, jetty, proxy, console-webapp, services/*) and deployed services (frontend, backend, console, pubapi, proxy). Key clarifications: - All four HTTP services (frontend, backend, console, pubapi) run the same nomulus Docker image built from the jetty/ module - services/* directories are legacy App Engine stubs with no logic - proxy can run as either a sidecar or a standalone cluster - Differentiated by environment argument and URL routing, not binaries Fixes google#2839
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR adds a new "Build Modules vs Deployed Services" section to
docs/architecture.mdthat resolves the recurring confusion about howNomulus subdirectories map to deployed services.
The codebase has two overlapping naming conventions:
core,jetty,proxy,console-webapp,services/backend,services/pubapi, etc.frontend,backend,console,pubapi,proxyKey clarifications in the documentation
frontend,backend,console,pubapi)run the same
nomulusDocker image built from thejetty/module.They are differentiated only by the environment argument passed to the
container and URL routing rules in the GKE Gateway, not by different
binaries.
jettyis not a service — it is the build module that produces theDocker image deployed as all four HTTP services.
services/subdirectories (backend,bsa,default,pubapi,tools) are legacy App Engine stubs. They have emptysrc/directoriesand contain no logic. They exist for Gradle compatibility only and are
not used in Kubernetes/Cloud Run deployments.
proxycan run either as a sidecar container in thefrontendpodor as a standalone cluster (with its own deployment manifests in
proxy/kubernetes/).console-webappAngular assets are bundled into thejettyDockerimage, not deployed separately.
Why environment-specific titles appear
The
/consoleand/registrarpaths serve the registrar console withAngular builds configured per environment (alpha, sandbox, qa, crash,
production), which can display different branding/titles.
Recommended starting environment
For new operators, the existing "Environments" section recommends
starting with the
SANDBOXenvironment. It has its own GCP project,database, and is isolated from production data — designed for learning
and registrar integration testing.
Fixes #2839
This change is