Skip to content

Commit fcf0a89

Browse files
jfarcandjfarcand
committed
feat: initial website and documentation setup
Migrated from Atmosphere/atmosphere repo: - Astro marketing site (website/) - Starlight documentation (docs/) - GitHub Actions workflow for building and deploying to GitHub Pages - Javadoc generation from core repo via cross-repo checkout
0 parents  commit fcf0a89

98 files changed

Lines changed: 29657 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/deploy.yml‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
name: Deploy website
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
# Rebuild when atmosphere core changes (triggered from main repo)
8+
repository_dispatch:
9+
types: [rebuild-site]
10+
# Nightly rebuild to pick up Javadoc changes from core repo
11+
schedule:
12+
- cron: '0 6 * * *'
13+
14+
permissions:
15+
contents: read
16+
pages: write
17+
id-token: write
18+
19+
concurrency:
20+
group: pages
21+
cancel-in-progress: false
22+
23+
jobs:
24+
build:
25+
runs-on: ubuntu-latest
26+
steps:
27+
- uses: actions/checkout@v4
28+
29+
# ── Marketing site (Astro) ──
30+
- uses: withastro/action@v3
31+
with:
32+
path: ./website
33+
env:
34+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
35+
36+
# withastro/action uploads to the default pages artifact.
37+
# Download it, merge in docs + javadoc, then re-upload.
38+
- name: Download Astro artifact
39+
uses: actions/download-artifact@v4
40+
with:
41+
name: github-pages
42+
path: _site_archive
43+
44+
- name: Extract Astro build
45+
run: |
46+
mkdir -p _merged
47+
tar -xf _site_archive/artifact.tar -C _merged
48+
49+
# ── Starlight docs ──
50+
- name: Set up Node.js
51+
uses: actions/setup-node@v4
52+
with:
53+
node-version: 22
54+
cache: 'npm'
55+
cache-dependency-path: docs/package-lock.json
56+
57+
- name: Build Starlight docs
58+
working-directory: docs
59+
run: npm ci && npm run build
60+
61+
- name: Merge docs into site
62+
run: cp -r docs/dist _merged/docs
63+
64+
# ── Javadoc (from main atmosphere repo) ──
65+
- name: Checkout atmosphere core
66+
uses: actions/checkout@v4
67+
with:
68+
repository: Atmosphere/atmosphere
69+
ref: main
70+
path: _atmosphere
71+
72+
- name: Set up JDK 21
73+
uses: actions/setup-java@v4
74+
with:
75+
java-version: '21'
76+
distribution: 'temurin'
77+
cache: 'maven'
78+
79+
- name: Extract project version
80+
id: version
81+
working-directory: _atmosphere
82+
run: |
83+
VERSION=$(./mvnw help:evaluate -Dexpression=project.version -q -DforceStdout)
84+
echo "version=$VERSION" >> "$GITHUB_OUTPUT"
85+
86+
- name: Compile sources
87+
working-directory: _atmosphere
88+
run: ./mvnw compile -pl modules/cpr -Pfastinstall -q
89+
90+
- name: Generate Javadoc
91+
working-directory: _atmosphere
92+
run: |
93+
DEPS_CP=$(./mvnw dependency:build-classpath -pl modules/cpr -Dmdep.outputFile=/dev/stdout -q)
94+
javadoc -d ../target/apidocs \
95+
-sourcepath modules/cpr/src/main/java \
96+
-classpath "$DEPS_CP" \
97+
-subpackages org.atmosphere \
98+
-source 21 \
99+
-Xdoclint:none \
100+
-quiet \
101+
-encoding UTF-8 \
102+
-windowtitle "Atmosphere ${{ steps.version.outputs.version }} API" \
103+
-doctitle "Atmosphere Framework ${{ steps.version.outputs.version }} API" \
104+
-header "Atmosphere ${{ steps.version.outputs.version }}" \
105+
-bottom "Copyright © 2008-2026 Async-IO.org. All rights reserved." \
106+
-link "https://docs.oracle.com/en/java/javase/21/docs/api/" \
107+
-link "https://jakarta.ee/specifications/platform/9/apidocs/"
108+
109+
- name: Merge Javadoc into site
110+
run: cp -r target/apidocs _merged/apidocs
111+
112+
# ── Upload merged artifact ──
113+
- name: Delete Astro-only artifact
114+
uses: geekyeggo/delete-artifact@v5
115+
with:
116+
name: github-pages
117+
118+
- name: Upload merged Pages artifact
119+
uses: actions/upload-pages-artifact@v3
120+
with:
121+
path: _merged
122+
123+
deploy:
124+
needs: build
125+
runs-on: ubuntu-latest
126+
environment:
127+
name: github-pages
128+
url: ${{ steps.deployment.outputs.page_url }}
129+
steps:
130+
- id: deployment
131+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
node_modules/
2+
dist/
3+
.astro/
4+
.DS_Store

‎docs/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
node_modules/
2+
dist/
3+
.astro/

‎docs/README.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Atmosphere Documentation
2+
3+
Atmosphere is a transport-agnostic real-time framework for the JVM. Write to a Broadcaster, and the framework delivers to every subscriber -- whether they're on a WebSocket, SSE stream, long-polling loop, gRPC channel, or MCP session.
4+
5+
- [**What's New in 4.0**](whats-new-4.0.md)
6+
7+
## Core
8+
9+
- [**Core Runtime**](core.md) -- Broadcaster, AtmosphereResource, `@ManagedService`, transport negotiation
10+
- [**Rooms & Presence**](rooms.md) -- Room management, join/leave, presence tracking, message history, AI virtual members
11+
12+
## Framework Integration
13+
14+
- [**Spring Boot**](spring-boot.md) -- Auto-configuration for Spring Boot 4.0+, gRPC transport, native image
15+
- [**Quarkus**](quarkus.md) -- Build-time processing for Quarkus 3.21+, native image
16+
17+
## AI / LLM
18+
19+
- [**AI Core**](ai.md) -- `AiSupport` SPI, `@AiEndpoint`, filters, routing, conversation memory
20+
- [**Spring AI Adapter**](spring-ai.md) -- `AiSupport` backed by Spring AI `ChatClient`
21+
- [**LangChain4j Adapter**](langchain4j.md) -- `AiSupport` backed by LangChain4j `StreamingChatLanguageModel`
22+
- [**Google ADK Adapter**](adk.md) -- `AiSupport` backed by Google ADK `Runner`
23+
- [**Embabel Adapter**](embabel.md) -- `AiSupport` backed by Embabel `AgentPlatform`
24+
25+
## Protocols
26+
27+
- [**gRPC Transport**](grpc.md) -- Bidirectional streaming via grpc-java
28+
- [**MCP Server**](mcp.md) -- Model Context Protocol server over WebSocket, SSE, or Streamable HTTP
29+
30+
## Client Libraries
31+
32+
- [**atmosphere.js (TypeScript)**](client-javascript.md) -- Browser client with React, Vue, and Svelte hooks
33+
- [**wAsync (Java)**](client-java.md) -- Async Java client for WebSocket, SSE, streaming, long-polling, gRPC
34+
35+
## Infrastructure
36+
37+
- [**Redis Clustering**](redis.md) -- Cross-node broadcasting via Redis pub/sub
38+
- [**Kafka Clustering**](kafka.md) -- Cross-node broadcasting via Kafka
39+
- [**Durable Sessions**](durable-sessions.md) -- Session persistence across restarts (InMemory, SQLite, Redis)
40+
41+
## Extensions
42+
43+
- [**Kotlin DSL**](kotlin.md) -- Builder API and coroutine extensions
44+
- [**Observability**](observability.md) -- Micrometer metrics, OpenTelemetry tracing, backpressure
45+
46+
## Additional Resources
47+
48+
- [Samples](../samples/) -- Runnable apps covering every transport and integration
49+
- [Javadoc](http://atmosphere.github.io/atmosphere/apidocs/)
50+
- [GitHub](https://github.com/Atmosphere/atmosphere)

‎docs/adk.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Google ADK Adapter
2+
3+
Bridges [Google Agent Development Kit (ADK)](https://github.com/google/adk-java) agent streams to Atmosphere's real-time broadcast infrastructure. ADK agents can push streaming texts to WebSocket, SSE, and gRPC browser clients.
4+
5+
## Maven Coordinates
6+
7+
```xml
8+
<dependency>
9+
<groupId>org.atmosphere</groupId>
10+
<artifactId>atmosphere-adk</artifactId>
11+
<version>4.0.15</version>
12+
</dependency>
13+
```
14+
15+
## Architecture
16+
17+
```
18+
Browser <- WS/SSE/gRPC -> Broadcaster <- AdkEventAdapter <- Flowable<Event> <- Runner <- LlmAgent
19+
```
20+
21+
## Quick Start
22+
23+
### AiSupport SPI (auto-detected)
24+
25+
```java
26+
@AiEndpoint(path = "/ai/chat", systemPrompt = "You are a helpful assistant")
27+
public class MyChat {
28+
29+
@Prompt
30+
public void onPrompt(String message, StreamingSession session) {
31+
session.stream(message); // uses ADK automatically when atmosphere-adk is on classpath
32+
}
33+
}
34+
```
35+
36+
### Direct Adapter Usage
37+
38+
```java
39+
// Build an ADK agent
40+
LlmAgent agent = LlmAgent.builder()
41+
.name("assistant")
42+
.model("gemini-2.0-flash")
43+
.instruction("You are a helpful assistant.")
44+
.build();
45+
46+
Runner runner = Runner.builder()
47+
.agent(agent)
48+
.appName("my-app")
49+
.build();
50+
51+
// Stream to an AtmosphereResource
52+
var session = StreamingSessions.start(resource);
53+
adkAdapter.stream(new AdkRequest(runner, userId, sessionId, prompt), session);
54+
```
55+
56+
### Low-Level Event Bridge
57+
58+
Bridge ADK events directly to a Broadcaster:
59+
60+
```java
61+
Flowable<Event> events = runner.runAsync(userId, sessionId,
62+
Content.fromParts(Part.fromText(prompt)));
63+
AdkEventAdapter.bridge(events, broadcaster);
64+
```
65+
66+
### ADK Broadcast Tool
67+
68+
Give your ADK agent a tool that can push messages to browser clients:
69+
70+
```java
71+
AdkBroadcastTool broadcastTool = new AdkBroadcastTool(broadcaster);
72+
73+
LlmAgent agent = LlmAgent.builder()
74+
.name("notifier")
75+
.model("gemini-2.0-flash")
76+
.instruction("Use the broadcast tool to send updates to users.")
77+
.tools(broadcastTool)
78+
.build();
79+
```
80+
81+
## Key Classes
82+
83+
| Class | Purpose |
84+
|-------|---------|
85+
| `AdkEventAdapter` | Subscribes to `Flowable<Event>` and forwards streaming texts to `StreamingSession` |
86+
| `AdkBroadcastTool` | ADK `BaseTool` that broadcasts messages via Atmosphere `Broadcaster` |
87+
| `AdkStreamingAdapter` | `AiStreamingAdapter` SPI impl bridging ADK Runner to StreamingSession |
88+
| `AdkAiSupport` | `AiSupport` SPI implementation (priority 100) |
89+
90+
## Samples
91+
92+
- [Spring Boot ADK Chat](../samples/spring-boot-adk-chat/) -- complete ADK chat example
93+
- [Spring Boot ADK Tools](../samples/spring-boot-adk-tools/) -- ADK tools with broadcasting
94+
95+
## See Also
96+
97+
- [AI Integration](ai.md) -- `AiSupport` SPI, `@AiEndpoint`, filters, routing
98+
- [Spring AI Adapter](spring-ai.md)
99+
- [LangChain4j Adapter](langchain4j.md)
100+
- [Embabel Adapter](embabel.md)
101+
- [Module README](../modules/adk/README.md)

0 commit comments

Comments
 (0)