Skip to content

Commit 0e4a5d9

Browse files
lukeocodeslukeocodes
committed
docs: add AGENTS.md and CLAUDE.md for AI coding assistants
1 parent 85dd85f commit 0e4a5d9

File tree

2 files changed

+167
-0
lines changed

2 files changed

+167
-0
lines changed

‎AGENTS.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# node-text-intelligence
2+
3+
Node.js demo app for Deepgram Text Intelligence.
4+
5+
## Architecture
6+
7+
- **Backend:** Node.js (JavaScript) on port 8081
8+
- **Frontend:** Vite + vanilla JS on port 8080 (git submodule: `text-intelligence-html`)
9+
- **API type:** REST — `POST /api/text-intelligence`
10+
- **Deepgram API:** Text Intelligence / Read API (`/v1/read`)
11+
- **Auth:** JWT session tokens via `/api/session` (WebSocket auth uses `access_token.<jwt>` subprotocol)
12+
13+
## Key Files
14+
15+
| File | Purpose |
16+
|------|---------|
17+
| `server.js` | Main backend — API endpoints and request handlers |
18+
| `deepgram.toml` | Metadata, lifecycle commands, tags |
19+
| `Makefile` | Standardized build/run targets |
20+
| `sample.env` | Environment variable template |
21+
| `frontend/main.js` | Frontend logic — UI controls, API calls, result rendering |
22+
| `frontend/index.html` | HTML structure and UI layout |
23+
| `deploy/Dockerfile` | Production container (Caddy + backend) |
24+
| `deploy/Caddyfile` | Reverse proxy, rate limiting, static serving |
25+
26+
## Quick Start
27+
28+
```bash
29+
# Initialize (clone submodules + install deps)
30+
make init
31+
32+
# Set up environment
33+
test -f .env || cp sample.env .env # then set DEEPGRAM_API_KEY
34+
35+
# Start both servers
36+
make start
37+
# Backend: http://localhost:8081
38+
# Frontend: http://localhost:8080
39+
```
40+
41+
## Start / Stop
42+
43+
**Start (recommended):**
44+
```bash
45+
make start
46+
```
47+
48+
**Start separately:**
49+
```bash
50+
# Terminal 1 — Backend
51+
node server.js
52+
53+
# Terminal 2 — Frontend
54+
cd frontend && corepack pnpm run dev -- --port 8080 --no-open
55+
```
56+
57+
**Stop all:**
58+
```bash
59+
lsof -ti:8080,8081 | xargs kill -9 2>/dev/null
60+
```
61+
62+
**Clean rebuild:**
63+
```bash
64+
rm -rf node_modules frontend/node_modules frontend/.vite
65+
make init
66+
```
67+
68+
## Dependencies
69+
70+
- **Backend:** `package.json` — Uses `corepack pnpm` — Node's built-in package manager version pinning.
71+
- **Frontend:** `frontend/package.json` — Vite dev server
72+
- **Submodules:** `frontend/` (text-intelligence-html), `contracts/` (starter-contracts)
73+
74+
Install: `corepack pnpm install`
75+
Frontend: `cd frontend && corepack pnpm install`
76+
77+
## API Endpoints
78+
79+
| Endpoint | Method | Auth | Purpose |
80+
|----------|--------|------|---------|
81+
| `/api/session` | GET | None | Issue JWT session token |
82+
| `/api/metadata` | GET | None | Return app metadata (useCase, framework, language) |
83+
| `/api/text-intelligence` | POST | JWT | Analyzes text for summaries, topics, sentiment, and intents. |
84+
85+
## Customization Guide
86+
87+
### Toggling Analysis Features
88+
The API supports four analysis features, each enabled independently via query parameters:
89+
90+
| Feature | Parameter | Values | Effect |
91+
|---------|-----------|--------|--------|
92+
| Summarize | `summarize` | `true`, `v2` | Generate text summary |
93+
| Topics | `topics` | `true` | Detect discussed topics |
94+
| Sentiment | `sentiment` | `true` | Analyze sentiment (positive/neutral/negative) |
95+
| Intents | `intents` | `true` | Detect user intents |
96+
97+
**Backend:** These are passed as query parameters to the Deepgram Read API. Enable/disable them in the backend handler or let the frontend control them.
98+
99+
**Frontend:** The frontend has checkboxes for each feature. Users select which analyses to run. To change defaults (e.g., always enable sentiment), edit `frontend/main.js`.
100+
101+
### Changing the Language
102+
Add `language=<code>` as a query parameter. Default is `en`. Supported languages depend on the feature — check Deepgram docs.
103+
104+
### Input Modes
105+
The app supports two input modes:
106+
1. **Text** — User pastes text directly
107+
2. **URL** — User provides a URL; the backend fetches and analyzes the text content
108+
109+
### Customizing the Response
110+
The full Deepgram response includes:
111+
- `results.summary.text` — Summary text
112+
- `results.topics.segments[].topics[].topic` — Detected topics with confidence
113+
- `results.sentiments.average` — Overall sentiment with score
114+
- `results.sentiments.segments[]` — Per-segment sentiment
115+
- `results.intents.segments[].intents[].intent` — Detected intents with confidence
116+
117+
You can modify the backend response formatter to include/exclude specific fields or add post-processing.
118+
119+
## Frontend Changes
120+
121+
The frontend is a git submodule from `deepgram-starters/text-intelligence-html`. To modify:
122+
123+
1. **Edit files in `frontend/`** — this is the working copy
124+
2. **Test locally** — changes reflect immediately via Vite HMR
125+
3. **Commit in the submodule:** `cd frontend && git add . && git commit -m "feat: description"`
126+
4. **Push the frontend repo:** `cd frontend && git push origin main`
127+
5. **Update the submodule ref:** `cd .. && git add frontend && git commit -m "chore(deps): update frontend submodule"`
128+
129+
**IMPORTANT:** Always edit `frontend/` inside THIS starter directory. The standalone `text-intelligence-html/` directory at the monorepo root is a separate checkout.
130+
131+
### Adding a UI Control for a New Feature
132+
1. Add the HTML element in `frontend/index.html` (input, checkbox, dropdown, etc.)
133+
2. Read the value in `frontend/main.js` when making the API call or opening the WebSocket
134+
3. Pass it as a query parameter or request body field
135+
4. Handle it in the backend `server.js` — read the param and pass it to the Deepgram API
136+
137+
## Environment Variables
138+
139+
| Variable | Required | Default | Purpose |
140+
|----------|----------|---------|---------|
141+
| `DEEPGRAM_API_KEY` | Yes | — | Deepgram API key |
142+
| `PORT` | No | `8081` | Backend server port |
143+
| `HOST` | No | `0.0.0.0` | Backend bind address |
144+
| `SESSION_SECRET` | No | — | JWT signing secret (production) |
145+
146+
## Conventional Commits
147+
148+
All commits must follow conventional commits format. Never include `Co-Authored-By` lines for Claude.
149+
150+
```
151+
feat(node-text-intelligence): add diarization support
152+
fix(node-text-intelligence): resolve WebSocket close handling
153+
refactor(node-text-intelligence): simplify session endpoint
154+
chore(deps): update frontend submodule
155+
```
156+
157+
## Testing
158+
159+
```bash
160+
# Run conformance tests (requires app to be running)
161+
make test
162+
163+
# Manual endpoint check
164+
curl -sf http://localhost:8081/api/metadata | python3 -m json.tool
165+
curl -sf http://localhost:8081/api/session | python3 -m json.tool
166+
```

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@AGENTS.md

0 commit comments

Comments
 (0)