Skip to content

Improve Getting Started and Building Apps for enterprise architecture evaluation #6288

Open

Description

@peholmst

This was generated by AI during triage.

Tell us about your request

Improve the Getting Started and Building Apps documentation for experienced Java developers and architects evaluating Vaadin for an enterprise project.

The current documentation provides enough guidance to build a convincing prototype, but leaves important architectural and operational questions unanswered along the main learning path. It demonstrates developer productivity more convincingly than it explains the commitment involved in adopting and operating Vaadin.

This review is based on main at f42ae9b6a. It is a documentation assessment, not a runtime benchmark. Some gaps below are missing guidance; others are discoverability problems where relevant material already exists elsewhere.

Preserve what already works

  • The quick start demonstrates components, event listeners, use of a Java library, and a production JAR.
  • Building Apps contains substantial guidance on application services, DTOs versus entities, transactions, optimistic locking, database migrations, and paginated grids.
  • Background jobs and server push address real concerns such as threading, cleanup, memory leaks, and excessive updates.
  • Browserless testing guides cover several application frameworks and realistic interactions.

Findings, in priority order

1. Introduce the runtime model and its architectural consequences early

An evaluator needs to understand where UI state lives, what happens on a button click, what is stored per user and per tab, which interactions require server round trips, and what happens when connectivity or a session is lost.

The quick start explains that Java UI code runs on the server, and Conceptual Layers explains the UI/application distinction. Neither provides a compact operational model covering state, latency, concurrency, and deployment.

Suggested improvement: Add a prominently linked “How a Vaadin application works” explanation with a request-flow diagram, session/UI lifetimes, and practical implications. Include guidance on suitability and the situations where client-side React views are useful.

2. Surface stateful deployment and scaling tradeoffs in Architecture

The architecture section discusses monoliths, microservices, and packaging, but the Vaadin-specific consequences of scaling are more important to an adoption decision than general architectural definitions.

The distributed deployment reference already explains sticky sessions, replication, serialization constraints, and Kubernetes Kit. Architecture should lead readers to it before they make deployment assumptions.

Suggested improvement: Explain how to evaluate:

  • Memory consumption per active session and realistic concurrent-user workloads.
  • Interaction latency under realistic network conditions.
  • User experience during node failure, scale-down, and deployment.
  • Session continuity, session draining, and accepting a reload as operational choices.

Provide a practical measurement approach rather than a universal concurrency claim.

3. Complete the route from tutorial to production

Creating a production JAR is covered. Operating an application is not presented as a coherent next step.

Next Steps links to views, data, security, a real database, and agentic development, but lacks an explicit route through testing, deployment, monitoring, and failure handling. Production documentation exists under Flow Reference.

Suggested improvement: Add a “Take this application to production” path covering production builds, containers, reverse proxies and push connections, environment configuration and secrets, health checks, logs and metrics, and CI. Reuse and link existing reference material.

4. Connect security guidance to enterprise authentication and authorization

Add Login teaches in-memory authentication and refers production readers to Spring Security documentation. Connecting an enterprise identity provider is likely an early proof-of-concept task.

A concrete OAuth2/Keycloak guide already exists, including role mapping, but Add Login does not link to it.

Suggested improvement: Provide a clear route from login setup to an enterprise identity provider, role mapping, logout, and security verification. Extend the guidance beyond roles with an example of record-level authorization (“this user may edit this customer”) and guidance or explicit scope boundaries for tenant isolation.

Protect Services also instructs readers to test method security while saying that the corresponding guide is not yet written. Complete that handoff.

5. Offer a faster evaluation route and a clear tutorial conclusion

The tutorial includes useful explanations, complete code per step, and realistic concerns such as optimistic locking. However, it asks for 20–45 minutes per step, and the reviewed tutorial pages do not link to a runnable finished tutorial repository.

The tutorial ends with a promise of more steps, while Building Apps opens with a work-in-progress notice. Together these weaken confidence in the completeness of the recommended development path.

Suggested improvement: Give the tutorial a clearly bounded outcome and useful conclusion. Provide a runnable reference application with authentication, a service boundary, a database migration, representative tests, and deployment instructions so experienced readers can inspect it before following the tutorial selectively.

6. Make commercial boundaries and maintenance considerations discoverable

An evaluator needs to distinguish capabilities available in the open-source core from commercial components, tools, operational kits, and support offerings.

Relevant information exists elsewhere: the testing reference explains that browserless testing is free and discusses TestBench, Selenium, and Playwright; Kubernetes Kit is marked commercial.

Suggested improvement: Provide an evaluation-oriented capability map and links to supported technologies, release support, upgrades, and licensing. Make technical and procurement dependencies understandable without duplicating pricing information throughout the tutorials.

7. Distinguish framework requirements from recommended defaults

Project Structure describes a Vaadin project as essentially Spring Boot and Maven, while other documentation supports plain Java, CDI, Quarkus, and Gradle. The recommended stack is reasonable, but should be explicitly identified as a recommendation.

The microservices guide says a separate API gateway is unnecessary because Vaadin can call services directly. Direct calls alone do not settle gateway requirements for routing, policy, or traffic management.

Suggested improvement: Review architectural wording to distinguish Vaadin constraints, recommended defaults, and choices that depend on the surrounding system.

Additional gaps to address or explicitly signpost

  • Consuming existing remote services, including timeouts and failure handling. The current Integration guide focuses on exposing an API.
  • Application-wide error handling and recovery.
  • Accessibility verification and internationalization.
  • A testing strategy combining service, database, browserless, and browser tests.

Proposed outcome

Create an architect’s evaluation path, reachable from Getting Started and Building Apps, that connects runtime architecture and suitability, state and scaling, enterprise identity, testing and deployment, and commercial/support boundaries.

Use this issue to coordinate the documentation improvements; the individual topics can be implemented separately.

Acceptance criteria

  • An experienced Java developer can find the evaluation path from both entry points without knowing the reference documentation structure.
  • The path explains Vaadin’s runtime model and the consequences of stateful UIs before deployment decisions are made.
  • Existing deployment, OAuth2, testing, compatibility, and licensing material is linked at the relevant decision points.
  • The tutorial has a clear conclusion and a route to a secured, tested, deployed application.
  • A runnable reference application is linked for readers who want to inspect a complete example first.
  • Architectural recommendations are clearly distinguished from framework requirements.
  • Remaining gaps are explicitly identified, with concrete next steps rather than broad promises of future content.

If you think this issue is important, add a 👍 reaction to help the community and maintainers prioritize this issue.

Activity

  1. peholmst commented on Oct 8, 2026

    @peholmst
    MemberAuthor

    Posted by Claude Code after an independent read of all 178 pages in Getting Started and Building Apps on main at f42ae9b, on behalf of @peholmst.

    A second review from the same persona reached the same seven findings, so this comment only adds what the issue does not yet say. It also separates the work: this issue stays the umbrella for the missing evaluation path, and the defects found in existing pages went into their own issues (listed at the end), because they can be fixed without waiting for new content.

    Additions to the findings

    1. Runtime model. Besides state, latency, and deployment, the model should cover the threading contract: one lock per VaadinSession (all tabs of one user serialize), why slow work in a listener or inside UI.access() blocks that user, and that the Spring SecurityContext is not propagated to background threads. Today the last point is covered only in background-jobs/jobs.adoc, while the server-push threading pages send readers to executors and virtual threads without mentioning it. The model should also state side by side that Flow views are denied by default while React views are accessible without authentication by default.

    2. Scaling. Two things the current pages assume a single JVM for, without saying so: the shared-signal broadcast examples in server-push/updates.adoc and reactive.adoc (see the single-JVM note in shared-signals.adoc), and @Scheduled jobs in Background Jobs, which run on every node. A "scaling push" guide (sticky sessions, WebSocket proxy configuration, fallback transports, replication) would fit under Server Push and link the distributed-deployment reference.

    3. Route to production. Overlaps #5203. Note that next-steps.adoc is currently linked from no page at all: the quick start sends readers to the tutorial, and the tutorial ends on the WIP block without a link onward. Whatever the production path becomes, it needs an entry point.

    4. Enterprise authentication. SSO Kit is marked deprecated, so the evaluation path should point at oauth2.adoc and VaadinSecurityConfigurer.oauth2LoginPage(...) and say what replaces the kit. SAML appears nowhere in the docs; if it is out of scope, say so.

    6. Commercial and maintenance boundaries. Supported Technologies is linked from neither section, so Java 21 and Spring Boot 4 are not stated up front. Within the two sections the only commercial markers are the AI controllers, the self-hosted MCP server, and the IDE table's star legend.

    7. Requirements vs defaults. Quarkus and CDI appear only in the browserless test setup pages. starters/templates.adoc links the Quarkus and Jetty starters but not the flow/integrations/quarkus and flow/integrations/cdi guides. Gradle has no presence in the main path and its only page is outdated for V25 (#2567, updated with specifics today).

    Additional gaps to add to the list

    • Testing strategy. Method-security testing is "planned, but not yet written"; nothing on service or repository tests; no CI guidance (and debug-tests.adoc notes Surefire does not display the failure tree, without saying how to surface it in CI); React views have no testing guidance; the "formerly UI Unit Testing" name appears only on the migration page. Introduce browser-less testing in the tutorial #1685 is the older request for tests in the tutorial.
    • Integration. Consuming REST (RestClient, timeouts, token propagation) and messaging are absent; Kafka is not mentioned anywhere in articles/.
    • JPA in a stateful UI. spring.jpa.open-in-view, LazyInitializationException, N+1 and fetch strategies, and the memory and serialization cost of holding entities in Grid, Binder, or the session. Not covered anywhere in the two sections.
    • Editing safely end to end. The form series and the consistency deep dive never meet: no example carries a version through a DTO, maps a service-side ConstraintViolationException back to Binder fields, or catches OptimisticLockingFailureException in a view. Bean Validation in Binder is a one-line NOTE.
    • App shell at scale. Unsaved-changes guards (BeforeLeaveObserver), error and 404 views, permission-filtered menus, i18n of titles and menus.
    • Internal component libraries. Filed as Document sharing components between a company's own applications (private repositories, BOM alignment, shared theme) #6295.
    • Auditing, soft deletes, multi-tenancy, caching, and CSV/Excel export are absent everywhere in the docs; each deserves at least an explicit signpost.

    Defects in existing pages, filed separately

  2. peholmst commented on Oct 8, 2026

    @peholmst
    MemberAuthor

    Posted by Claude Code on behalf of @peholmst, as input to finding 5 (a bounded tutorial outcome).

    Which steps the tutorial is missing

    Measured against what tutorial/index.adoc promises ("a complete application with a database, forms, and navigation"), three steps are missing. Everything else that came up in the review belongs in Building Apps, not here.

    1. A wrap-up page. deep-link.adoc ends on the 🚧 "only a pause" block with no link onward, and no finished repository is linked from any step. A short closing page that recaps what was built, links Next Steps, and links a runnable finished project is the cheapest fix in this whole issue and removes the strongest "abandoned" signal.
    2. An application shell with a second view. Seven steps produce one view at @Route(""). The promised "navigation" is a route parameter on that view. One step that adds a main layout with a side menu and a second, deliberately trivial view (a placeholder for orders or deliveries from the Click & Collect story) would make the promise true and teach the one structure nearly every real application has. Deep Link fits naturally after it.
    3. A test. No step contains a test of any kind, and the tutorial never mentions the browserless testing guides in Building Apps. One step with a single browserless test of the product view, perhaps ten lines of test code, shows the strongest argument for a server-side Java UI. Introduce browser-less testing in the tutorial #1685 asked for this against the previous tutorial and still applies.

    Two smaller omissions can be folded into existing steps rather than added: delete is the missing quarter of CRUD and fits in Edit Details as one section with a confirm dialog; login is better offered as the first Next Steps exercise against the finished application, since Add Login already exists as a guide.

    Not worth adding to the tutorial: Flyway and a real database, deployment, i18n, server push, deeper validation. The tutorial already links to Building Apps for these.

    Paying for the new steps

    The length problem is not the step count. It is the listings. In every later step, a third to half of the page is the full-file listing at the end, and the instruction sections repeat whole classes after each small change:

    Step Instruction lines Complete-code listing lines
    List Data 216 90
    Sort & Filter 409 119
    Show Details 665 370
    Edit Details 797 456
    Add Data 1110 603
    Deep Link 677 634

    If the instructions showed only the changed lines and each step kept one collapsed full listing at the end, the existing seven steps would shrink by roughly a third. That buys a shell step and a test step without making the tutorial longer than it is today.

    Suggested sequence

    Setup, List Data, Sort & Filter, Show Details, Edit Details (with delete), Add Data, Add Navigation (shell plus second view), Deep Link, Test the View, Wrap Up (with the finished repository and the login exercise pointing at Next Steps).

  3. self-assigned this
    on Oct 8, 2026
  4. peholmst commented on Oct 10, 2026

    @peholmst
    MemberAuthor

    Re-review posted by Claude Code on behalf of @peholmst. Checked against main at 669b9a7 (32 commits after the reviewed f42ae9b; 113 files changed under Getting Started and Building Apps). Every status below was verified in the tree, not inferred from PR titles.

    Updated against main at 21e829d, after #6370 and #6371 merged. Changed: finding 6, a row for #6371, the remaining-work list, and the acceptance criteria. The previous update, at a575789 after #6364, #6365, and #6368, changed #2567 and findings 1, 2, 3, and 7.

    Defect issues

    Issue State Verified in the tree
    #6289 security guidance Closed @EnableMethodSecurity is now required and shown in the React guide, with a caution box; the REST @Order sentence now says "a lower @Order value"; the logout success URL is permitted explicitly and the logout view no longer sits on /logout; React/Flow opposite defaults have a side-by-side box.
    #6290 transactions and boundaries Closed @TransactionalEventListener in Add a Service, Event-Triggered Jobs, and a rewritten Eventual Consistency; @Transactional added to the service examples; the "repository from the UI" sidebars replaced by a Calling Repositories from Views section with four explicit conditions; startup trigger uses ApplicationRunner; saveAndFlush explained.
    #6291 code samples Closed Spot checks pass: Reactor subscribe(onNext, onError), the virtual-thread and executor examples do the work outside UI.access(), route template fixes, swapped React callouts, Wikipedia link, "LM Studio". The custom-field page shrank by about 1,000 lines and its examples are compiled.
    #6292 stubs and placeholders Closed Zero visible WIP markers, zero // TODO comments, and zero front-matter-only landing pages remain in the two sections. All seven landing pages have an intro and a reading order. Strong and Eventual Consistency are real pages.
    #6293 terminology and theme Closed "Hilla" no longer appears outside react/; Lumo tokens remain only where flagged.
    #6295 internal component library Closed New share-component.adoc: private repository, BOM alignment, shared theme and tokens, versioning, isolated tests. Solid.
    #6294 tutorial patterns Open Six of seven items done; grid identity waits on vaadin/flow-components#10393.
    #2567 Gradle page Closed Fixed by #6364. gradle.adoc now requires Java 21 and Gradle 8.14, takes the plugin and Spring Boot versions from attributes, uses jakarta.servlet 6.1, and runs Gretty 5 with Jetty 12 or Tomcat 11. #6365 did the same for the Hilla Gradle reference.
    #6371 Spring Boot minimum Merged Found during finding 6. The Upgrading Guide said Vaadin 25 "Requires Spring Boot 4.0.4 or newer", which was the 25.1 requirement and contradicted Supported Technologies. It now says 4.1, matching the 25.2 and 25.3 release notes.

    The seven findings of this issue

    # Finding Status
    1 Runtime model explained early Done in #6368. New Runtime Model page ("How a Vaadin Application Works"), first in Architecture: a request-flow diagram; session, UI, view, and singleton lifetimes and what they mean for memory, reloads, and idle sessions; the session lock, UI.access(), and thread-local state including the SecurityContext; how browser and server stay in sync, what happens when the connection is lost, and resynchronization (which reruns detach and attach listeners); deployment consequences; and a Flow/React comparison with the opposite access defaults and guidance on choosing, including team skills. Linked from the Getting Started index, the quick start, Next Steps, the Building Apps and Architecture indexes, Layers, Monoliths, and React Views. The server-push Threads page gained Calling Protected Services (DelegatingSecurityContextRunnable).
    2 Stateful deployment and scaling in Architecture Partly. Monoliths links Distributed Deployment for sticky sessions and session replication. The shared-signal broadcast examples now carry a per-JVM caution. The runtime model page now states the consequences: what breaks without sticky sessions, sessions lost with a server, per-instance in-memory state, and push through proxies. It also says to size servers by load testing rather than a rule of thumb, and notes the roughly 14% per-user memory saving from compact object headers on Java 27. Still missing: a how-to for the measurement itself (memory per session, latency under realistic network conditions, what users see on node failure or scale-down), and a note that @Scheduled jobs run on every instance.
    3 Route from tutorial to production Partly. Next Steps gained Test Your Application and Deploy to Production sections, and is now reachable from the quick start, the tutorial setup, and the final tutorial step. The deploy section is a pointer to Flow Reference, and since #6368 it sends readers to the runtime model page before they decide how to deploy. The coherent production path (containers, proxies and push, secrets, health checks, logs and metrics, CI) is still #5203.
    4 Enterprise authentication Partly. The Security landing page now points identity-provider users to OAuth2 Authentication, and Protect Services has a Testing Method Security section, closing the "not yet written" handoff. Still missing: a Building Apps guide that walks from Add Login to an identity provider with role mapping and logout, record-level authorization, and tenant isolation scope.
    5 Tutorial conclusion and reference app Partly. The tutorial now ends with Add Tests, which closes with a proper recap and a button to Next Steps; the index describes the real scope. No runnable finished-application repository is linked from any step.
    6 Commercial and maintenance boundaries Done in #6370. New Licensing, Support & Maintenance page, last in Architecture. It covers what the Apache 2.0 core includes (the framework, the core UI components, browserless testing, and the AI integration core), the kinds of features that commercial subscriptions add, and how to recognize them in the docs (the $ badge and the Commercial Feature notice). It also covers what a license means for developer machines, CI, and production, and the release and free-maintenance model. The page names no commercial products or subscription tiers, because licensing changes; vaadin.com/pricing is the source of truth. Linked from the Getting Started index, Next Steps (new Plan for Licensing & Upgrades section), the Building Apps and Architecture indexes, and the runtime model. Supported Technologies is now linked from the Getting Started index, Development Environment, Next Steps, and Project Structure, and the Upgrading Guide from Next Steps. Copilot, free since 25.1, lost its stale commercial markers on the Tools card and the Licenses page.
    7 Requirements vs recommended defaults Mostly done. Project Structure says "Spring Boot and Maven are recommendations, not requirements" and links Gradle and GraalVM; the microservices BFF wording is corrected. The Gradle page that Project Structure links to is now current (#6364). Templates still doesn't link the Quarkus and CDI integration guides.

    Additional gaps listed in the issue

    • Application-wide error handling: done. Handle Errors is a strong page: a copy-paste error handler with error IDs, the default-behavior table, custom not-found and access-denied views, the Spring MVC contrast, and Handle Exceptions from Services with an optimistic-locking recovery example. That last section also covers most of the "edit an entity safely end to end" gap from the first comment.
    • Consuming remote services: open. The Integration landing page now says to make outbound calls from application services, but there is no guide, and messaging is still absent.
    • Accessibility and i18n: open. No page in either section.
    • Testing strategy: partly. The tutorial has a service test and browserless view tests, and Protect Services shows a method-security test. There is still no page that combines service, database, browserless, and browser tests, and nothing on CI.

    Tutorial steps (second comment)

    • Test step: done, and well made. Service test with Bean Validation and @Transactional rollback, three browserless view tests that find components the way a user does, and a "make it fail" exercise for both.
    • Conclusion: done, as the Next Steps section of Add Tests rather than a separate page. Sufficient.
    • Application shell with a second view: open. The tutorial still has one view at @Route("") and no layout, menu, or second view.
    • Delete: open.
    • Login as a Next Steps exercise: done in substance; Add Tests ends with "you need to secure it, move it to a real database, and deploy it".
    • Trimming the listings: not done, and the tutorial grew. The six original steps went from 6,190 to 6,324 lines, plus 359 for Add Tests. Edit Details grew from 1,260 to 1,500 lines with the service and validation work. Listings are still 35 to 50 percent of each later step.

    What remains, in priority order

    1. Finding 4, an enterprise authentication guide in Building Apps, beyond the pointer.
    2. Finding 5, the finished-application repository, plus the shell and delete steps if the tutorial is to deliver "navigation".
    3. Findings 2 and 3, the measurement how-to (the runtime model page now explains why it matters) and the production path (How-to guides for production #5203). Add the @Scheduled note to Background Jobs.
    4. Signposts for consuming services, messaging, i18n, accessibility, JPA in a stateful UI, and a test-strategy page.

    Acceptance criteria

    • Evaluation path findable from both entry points: partly. The runtime model and licensing pages are linked from both Getting Started and Building Apps, and Next Steps now leads on to commercial boundaries and upgrades. No path yet leads to scaling, identity, or a testing strategy.
    • Runtime model before deployment decisions: done in docs: explain the runtime model of a Vaadin application #6368, and Next Steps points to it before Deploy to Production.
    • Existing deployment, OAuth2, testing, compatibility, and licensing material linked at decision points: yes. Compatibility and licensing were added in docs: map free and commercial features, support, and maintenance #6370.
    • Tutorial has a clear conclusion and a route to a secured, tested, deployed application: conclusion yes, route via Next Steps yes.
    • Runnable reference application linked: no.
    • Recommendations distinguished from requirements: yes in Project Structure.
    • Remaining gaps explicitly identified: the stubs and TODOs are gone; this comment is the current list.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions