Skip to content

Instantly share code, notes, and snippets.

@jfarcand

jfarcand/atmosphere-docs-analysis.md Secret

Last active March 27, 2026 20:37
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save jfarcand/a3f3fed751fb58de44d7a7109bb53f6c to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save jfarcand/a3f3fed751fb58de44d7a7109bb53f6c to your computer and use it in GitHub Desktop.
Download ZIP
Atmosphere Documentation Overhaul — Full Analysis
Raw
atmosphere-docs-analysis.md

Atmosphere Documentation Audit — Final Version

Date: 2026-03-27 Scope: README.md, docs/, ../atmosphere.github.io/docs Constraint: Analysis and proposal only — no code changes

Executive Summary

Atmosphere's documentation is close to publication quality. Feature claims are substantively accurate — the code delivers what it promises. But the docs have real issues that must be fixed before publishing on ai4jvm:

  1. docs/protocols.md uses @McpServer — an annotation that does not exist. The correct pattern is @Agent with MCP method annotations.
  2. README says "Pick any LLM library" — should enumerate the 5 supported adapters.
  3. README lists spring-boot-embabel-chat sample — it's commented out of the build (pom.xml:541) and the directory samples/spring-boot-embabel-chat/ doesn't exist.
  4. Planned-but-unimplemented features in skill-files (channels routing validation, guardrails metadata export) are not surfaced in the README.
  5. Missing reference docs for @Agent, @Coordinator, and configuration.
  6. No docs governance: two doc trees (docs/ and atmosphere.github.io/docs) with no declared relationship.

Part 1: What Atmosphere Is (Verified Against Code)

Version and Build

Property Value
Root POM Version 4.0.28-SNAPSHOT
Java JDK 21+ (--release 21)
Jakarta EE 10 (Servlet 6.0, WebSocket 2.1)
Virtual Threads Enabled by default (org.atmosphere.useVirtualThreads, configurable)
Maven 3.6.3+

Module Inventory (26 modules)

Core:

Module ArtifactId Purpose
cpr atmosphere-runtime Transport abstraction, Broadcaster pub/sub, Room API, presence
agent atmosphere-agent @Agent processor, CommandRouter, SkillFileParser
ai atmosphere-ai AI/LLM streaming SPI, StreamingSession, @Prompt, @AiTool
ai-test atmosphere-ai-test Test fixtures for AI agents
coordinator atmosphere-coordinator @Coordinator, @Fleet, AgentFleet, journal, evaluation

AI Backends (AgentRuntime SPI) — these are the supported adapters:

Module ArtifactId Backend Version
(built-in) atmosphere-ai OpenAI-compatible (Gemini, OpenAI, Ollama) —
spring-ai atmosphere-spring-ai Spring AI ChatClient 2.0.0-M2
langchain4j atmosphere-langchain4j LangChain4j StreamingChatModel 1.12.2
adk atmosphere-adk Google ADK LlmAgent 0.2.0
embabel atmosphere-embabel Embabel GOAP planning 0.3.4

Protocols (auto-registered via classpath):

Module ArtifactId Protocol Endpoint
mcp atmosphere-mcp MCP /atmosphere/agent/{name}/mcp
a2a atmosphere-a2a A2A (JSON-RPC 2.0) /atmosphere/agent/{name}/a2a
agui atmosphere-agui AG-UI (SSE) /atmosphere/agent/{name}/agui

Channels:

Module ArtifactId Platforms
channels atmosphere-channels Slack, Telegram, Discord, WhatsApp, Messenger

Framework Integration:

Module ArtifactId Target
spring-boot-starter atmosphere-spring-boot-starter Spring Boot 4.0.2+
spring-boot3-starter atmosphere-spring-boot3-starter Spring Boot 3.x
quarkus-extension atmosphere-quarkus-extension Quarkus 3.31.3+

Clustering and Sessions:

Module ArtifactId Backend
redis atmosphere-redis Lettuce 6.5.5
kafka atmosphere-kafka Kafka 3.9.1
durable-sessions atmosphere-durable-sessions SPI (in-memory default)
durable-sessions-sqlite atmosphere-durable-sessions-sqlite SQLite
durable-sessions-redis atmosphere-durable-sessions-redis Redis

Other:

Module Purpose
grpc (atmosphere-grpc) gRPC transport (gRPC 1.79.0)
kotlin (atmosphere-kotlin) Kotlin DSL, coroutines (Kotlin 2.1.10)
protocol-common Shared protocol base classes
wasync Java async WebSocket client
rag (atmosphere-rag) RAG context providers (Spring AI VectorStore, LangChain4j EmbeddingStore)

Key Dependencies

Dependency Version
Jetty 12.0.32
Tomcat 11.0.18
Spring Boot 4.0.2
Quarkus 3.31.3
Jackson 2.18.6

Part 2: Verified Findings (Issues)

Issue 1: @McpServer does not exist

Severity: P0

docs/protocols.md:18 shows:

@McpServer(name = "my-tools", path = "/atmosphere/mcp")
public class MyTools { ... }

This annotation does not exist. The directory modules/mcp/src/main/java/org/atmosphere/mcp/annotation/ contains only: McpParam.java, McpPrompt.java, McpResource.java, McpTool.java. No McpServer.java.

The correct pattern (from the working sample samples/spring-boot-mcp-server/):

@Agent(name = "atmosphere-demo", version = "1.0.0", endpoint = "/atmosphere/mcp", headless = true)
public class DemoMcpServer {
    @McpTool(name = "greet", description = "Say hello")
    public String greet(@McpParam(name = "name") String name) { ... }
}

MCP is auto-registered when atmosphere-mcp is on the classpath. modules/mcp/README.md confirms this.

Fix: Update docs/protocols.md to use @Agent. Remove all @McpServer references from docs.

Issue 2: "Pick any LLM library" overstates

Severity: P0

README.md:9: "Pick any LLM library."

Atmosphere supports 5 specific backends via the AgentRuntime SPI: built-in (OpenAI-compatible), Spring AI, LangChain4j, Google ADK, Embabel. It does not support arbitrary LLM libraries — you need an adapter.

Fix: Replace with "Supports 5 AI backends" and list them explicitly.

Issue 3: Embabel sample listed but not buildable

Severity: P0

pom.xml:541 has samples/spring-boot-embabel-chat commented out with: "Embabel requires Spring Boot 3.5; will be supported when SB 3.5 module lands." The samples/spring-boot-embabel-chat/ directory does not exist. But the README sample table and current docs reference it.

Fix: Remove from README sample table or mark clearly as "not yet available."

Issue 4: Skill-file planned features not surfaced

Severity: P0

docs/skill-files.md:29: Channels section — "routing validation is planned but not yet implemented." docs/skill-files.md:30: Guardrails section — "Protocol metadata export is planned but not yet implemented."

README shows skill files with ## Channels and ## Guardrails sections as working features without noting these limitations.

Fix: Add caveat in README skill-files section, or note in a Limitations section.

Issue 5: Multi-agent NL routing is first-agent-wins

Severity: P1

docs/channels.md:36: "natural-language messages go to the first agent with a pipeline; only command routing supports multi-agent dispatch."

This is documented in channels.md but not in the README. Users with multiple agents will hit this silently.

Fix: Add to README limitations or channels section.

Issue 6: No Maven coordinates in README

Severity: P0

The README has no <dependency> block. A developer's first question — "how do I add this to my project?" — goes unanswered.

Fix: Add Maven/Gradle coordinates after the intro, before code examples.

Issue 7: No version stated in README

Severity: P1

The version (4.0.x) appears nowhere in the README.

Fix: State in requirements section.

Issue 8: Marketing tone in README

Severity: P1

  • "The real-time infrastructure layer for Java AI agents" — tagline
  • "Why not use Spring AI / LangChain4j / ADK directly?" — sales pitch
  • Bullet list reads like a pitch deck

Fix: Rewrite with dev tone. State what it does. Drop rhetorical questions.

Part 3: Documentation Governance

Current state

Two documentation trees exist with no declared relationship:

  1. atmosphere/docs/ — 4 reference files (annotations, channels, protocols, skill-files). Lives in the main repo, versioned with the code.
  2. atmosphere.github.io/docs/ — 21 pages covering core, integrations, clients, infrastructure. Separate repo, Astro-based static site.

They overlap on MCP/A2A/AG-UI (protocols.md exists in both) with different content. This causes drift — the @McpServer bug exists in docs/protocols.md but not in the working sample.

Proposed governance

atmosphere/docs/ is the canonical source for reference documentation. It ships with the code and stays in sync with annotations, SPIs, and behavior changes.

atmosphere.github.io/docs/ is the publish target for guides, tutorials, and integration deep-dives. It may link to canonical docs but should not duplicate reference material.

When both trees cover the same topic, the in-repo docs/ version is authoritative. Published docs should link to it or be generated from it.

Part 4: docs/ Assessment

Existing files

File Quality Notes
annotations.md Excellent Complete, accurate reference for all annotations
protocols.md Has bug Uses non-existent @McpServer. Otherwise good structure.
channels.md Good Includes known limitations
skill-files.md Good Honestly marks planned features

Missing files

File Content needed
agent.md @Agent lifecycle, headless vs full-stack, classpath wiring, endpoint paths
coordinator.md @Coordinator, @Fleet, AgentFleet API, journal SPI, evaluation SPI, test stubs
configuration.md All env vars, init-params, Spring Boot/Quarkus properties in one place

Part 5: atmosphere.github.io/docs/ Assessment

Index is stale

The README.md index doesn't list: Agent module, Coordinator, Channels, A2A protocol, AG-UI protocol.

Existing pages — all accurate

21 pages covering core, Spring Boot, Quarkus, AI adapters, MCP, gRPC, clients, Redis, Kafka, durable sessions, Kotlin, observability, React Native, What's New. Quality is consistently good.

Missing pages

Page Content
agent.md @Agent deep dive
coordinator.md Multi-agent orchestration
channels.md Multi-channel routing, platform setup
a2a.md A2A protocol, Agent Card, TaskContext
agui.md AG-UI streaming, CopilotKit compat

Part 6: Samples Inventory

Working samples (22)

Category Sample Stack
Chat spring-boot-chat Spring Boot 4.0
Chat quarkus-chat Quarkus 3.21+
Chat embedded-jetty-websocket-chat Embedded Jetty
Chat grpc-chat gRPC + Spring Boot
Chat chat Servlet WAR
AI spring-boot-ai-chat Built-in (Gemini/OpenAI/Ollama)
AI spring-boot-langchain4j-chat LangChain4j
AI spring-boot-spring-ai-chat Spring AI
AI spring-boot-adk-chat Google ADK
AI spring-boot-langchain4j-tools LangChain4j + @Tool
AI spring-boot-ai-tools LangChain4j + @AiTool
AI spring-boot-adk-tools ADK + @AiTool
AI spring-boot-ai-classroom Multi-persona, Expo RN
Agent spring-boot-agent-chat @Agent + commands
Agent spring-boot-dentist-agent @Agent + Slack + Telegram
Protocol spring-boot-mcp-server MCP
Protocol spring-boot-a2a-agent A2A
Protocol spring-boot-agui-chat AG-UI
Multi-Agent spring-boot-multi-agent-startup-team @Coordinator + @Fleet
Infra spring-boot-durable-sessions SQLite/Redis sessions
Infra spring-boot-otel-chat OpenTelemetry
Infra spring-boot-channels-chat Multi-channel

Not available

Sample Status Reason
spring-boot-embabel-chat Commented out of build Requires Spring Boot 3.5 compat work

Part 7: README Claims — Verification

Claim Status Notes
Transport-agnostic runtime Verified WebSocket, SSE, Long-polling, gRPC all implemented
@Agent auto-wires protocols by classpath Verified MCP, A2A, AG-UI auto-registered
Same agent on Web, Slack, Telegram, Discord Verified atmosphere-channels routes cross-platform
@Coordinator manages agent fleet Verified Sequential, parallel, local/remote dispatch
Skill files as Markdown with YAML frontmatter Verified With caveats: channels routing and guardrails export are planned
Switch backends by changing one dependency Verified AgentRuntime SPI with 5 adapters
Durable sessions survive restarts Verified SQLite + Redis implementations
Native image support Verified Spring Boot GraalVM hints, Quarkus build-time processing
"Pick any LLM library" Overstated 5 specific adapters, not arbitrary libraries
@McpServer annotation Does not exist docs/protocols.md:18 uses it; modules/mcp/src/main/java/org/atmosphere/mcp/annotation/ has no McpServer.java; sample uses @Agent
Embabel sample Not buildable Commented out at pom.xml:541; samples/spring-boot-embabel-chat/ does not exist

Part 8: Prioritized Remediation

P0 — Must fix before ai4jvm publication

  1. Fix @McpServer in docs/protocols.md — Replace with @Agent pattern matching the working sample
  2. README rewrite — Dev tone, Maven coordinates first, version stated, explicit adapter list (not "any"), limitations section
  3. Fix embabel sample listing — Remove from README table or mark as unavailable
  4. Surface planned limitations — Skill-file channels routing and guardrails export caveats

P1 — Should fix soon after

  1. Create docs/agent.md — @Agent reference doc
  2. Create docs/coordinator.md — @Coordinator reference doc
  3. Create docs/configuration.md — All env vars and config in one place
  4. Update atmosphere.github.io/docs/ index — Add missing sections
  5. Create new pages in atmosphere.github.io/docs/ — agent, coordinator, channels, a2a, agui
  6. Add multi-agent NL routing caveat to README
  7. State version in README
  8. Clarify virtual threads — Document the config key and behavior in configuration.md

P2 — Later cleanup

  1. ai4jvm SPEC.md entry — Can be done independently
  2. Docs governance — Declare canonical source vs publish target, consider CI drift check
  3. Expand Redis/Kafka docs — More examples

Part 9: Proposed ai4jvm Entry

Under "Agent Frameworks and Libraries" in SPEC.md:

### Atmosphere
- **Badge:** Framework
- **Description:** Transport-agnostic agent runtime for Java 21+. Annotate a class
  with @Agent and the framework exposes it via WebSocket, SSE, gRPC, MCP, A2A, and
  AG-UI based on which modules are on the classpath. Pluggable AI backends: Spring AI,
  LangChain4j, Google ADK, Embabel. Runs on Spring Boot 4.0 or Quarkus 3.21+.
- **Links:** [Docs](https://atmosphere.github.io/docs/) ·
  [GitHub](https://github.com/Atmosphere/atmosphere)

Part 10: Proposed README Structure

# Atmosphere

Transport-agnostic agent runtime for Java 21+.

## Requirements
## Install (Maven/Gradle)
## Minimal Example (@Agent that compiles)
## @Agent — Classpath-Driven Wiring (table)
## @Coordinator — Multi-Agent Orchestration
## Transports (table)
## Protocols — MCP, A2A, AG-UI (table)
## Channels (table)
## AI Backends (table, explicit list)
## Skills
## Client — atmosphere.js
## Annotation Compatibility (table)
## Samples (table, with availability status)
## CLI
## Known Limitations
## Documentation (links)
## License

Style: No rhetorical questions. No superlatives. Tables for feature matrices. Every claim verifiable by code or sample.

Definition of Done — P0

All of the following must be true before publishing on ai4jvm:

  • docs/protocols.md — no reference to @McpServer; MCP example uses @Agent with @McpTool/@McpResource/@McpPrompt
  • README.md — contains Maven <dependency> coordinates for atmosphere-spring-boot-starter and atmosphere-agent
  • README.md — states version (4.0.x) in requirements section
  • README.md — lists the 5 supported AI backends by name; no "any LLM library" language
  • README.md — spring-boot-embabel-chat either removed from sample table or marked "not yet available"
  • README.md — skill-files section notes that channels routing validation and guardrails metadata export are planned
  • README.md — has a "Known Limitations" section covering: first-agent NL routing, channel AiInterceptor gap, Quarkus loadOnStartup constraint
  • README.md — no rhetorical questions, no sales pitch sections, no superlatives
  • All code examples in README compile against the actual annotation set (spot-check imports)
  • docs/protocols.md MCP example matches samples/spring-boot-mcp-server/ source
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment