Skip to content

Commit 14647ea

Browse files
Fabien83560Fabien83560
committed
Initialize VitePress documentation site
0 parents  commit 14647ea

13 files changed

Lines changed: 3225 additions & 0 deletions

File tree

‎.github/workflows/deploy.yml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: Deploy Docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: pages
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
name: Build
20+
runs-on: ubuntu-latest
21+
22+
steps:
23+
- name: Checkout
24+
uses: actions/checkout@v4
25+
26+
- name: Setup Node.js
27+
uses: actions/setup-node@v4
28+
with:
29+
node-version: 22
30+
cache: npm
31+
32+
- name: Setup GitHub Pages
33+
uses: actions/configure-pages@v4
34+
35+
- name: Install dependencies
36+
run: npm ci
37+
38+
- name: Build VitePress
39+
run: npm run build
40+
41+
- name: Upload artifact
42+
uses: actions/upload-pages-artifact@v3
43+
with:
44+
path: docs/.vitepress/dist
45+
46+
deploy:
47+
name: Deploy to GitHub Pages
48+
runs-on: ubuntu-latest
49+
needs: build
50+
51+
environment:
52+
name: github-pages
53+
url: ${{ steps.deployment.outputs.page_url }}
54+
55+
steps:
56+
- name: Deploy
57+
id: deployment
58+
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+
docs/.vitepress/dist
3+
docs/.vitepress/cache
4+
.env

‎docs/.vitepress/config.js‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
import { defineConfig } from 'vitepress'
2+
3+
export default defineConfig({
4+
title: 'APIForge',
5+
description: 'API observability & intelligence — local-first, privacy-first',
6+
base: '/docs/',
7+
8+
head: [
9+
['link', { rel: 'icon', href: '/docs/favicon.ico' }],
10+
['meta', { name: 'theme-color', content: '#0066FF' }],
11+
['meta', { property: 'og:type', content: 'website' }],
12+
['meta', { property: 'og:title', content: 'APIForge Docs' }],
13+
['meta', { property: 'og:description', content: 'API observability SDK — local-first, privacy-first. Up and running in 5 minutes.' }],
14+
],
15+
16+
themeConfig: {
17+
logo: { light: '/logo-light.svg', dark: '/logo-dark.svg', alt: 'APIForge' },
18+
19+
nav: [
20+
{ text: 'Guide', link: '/guide/getting-started' },
21+
{ text: 'Features', link: '/features/insights' },
22+
{ text: 'API Reference', link: '/guide/configuration' },
23+
{
24+
text: 'v0.1.0',
25+
items: [
26+
{ text: 'Changelog', link: 'https://github.com/APIForge-Organisation/sdk-nodejs/blob/main/CHANGELOG.md' },
27+
{ text: 'npm', link: 'https://www.npmjs.com/package/apiforgejs' },
28+
],
29+
},
30+
],
31+
32+
sidebar: {
33+
'/guide/': [
34+
{
35+
text: 'Getting Started',
36+
items: [
37+
{ text: 'What is APIForge?', link: '/guide/what-is-apiforge' },
38+
{ text: 'Quick Start', link: '/guide/getting-started' },
39+
{ text: 'Configuration', link: '/guide/configuration' },
40+
],
41+
},
42+
{
43+
text: 'Dashboard',
44+
items: [
45+
{ text: 'Local Dashboard', link: '/guide/dashboard' },
46+
],
47+
},
48+
],
49+
'/features/': [
50+
{
51+
text: 'Features',
52+
items: [
53+
{ text: 'Automatic Insights', link: '/features/insights' },
54+
{ text: 'Health Score', link: '/features/health-score' },
55+
{ text: 'Release Tracking', link: '/features/release-tracking' },
56+
],
57+
},
58+
],
59+
},
60+
61+
socialLinks: [
62+
{ icon: 'github', link: 'https://github.com/APIForge-Organisation' },
63+
{ icon: 'npm', link: 'https://www.npmjs.com/package/apiforgejs' },
64+
],
65+
66+
editLink: {
67+
pattern: 'https://github.com/APIForge-Organisation/docs/edit/main/docs/:path',
68+
text: 'Edit this page on GitHub',
69+
},
70+
71+
footer: {
72+
message: 'Released under the MIT License.',
73+
copyright: 'Copyright © 2026 APIForge',
74+
},
75+
76+
search: {
77+
provider: 'local',
78+
},
79+
},
80+
})

‎docs/features/health-score.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Health Score
2+
3+
The Health Score is a single **0–100 number** that summarizes the overall health of your API at a glance. It is computed continuously and displayed prominently at the top of the dashboard.
4+
5+
## Calculation
6+
7+
The score combines four weighted dimensions:
8+
9+
| Dimension | Weight | What is measured |
10+
|---|---|---|
11+
| **Availability** | 30% | Ratio of 2xx responses over the last 24 hours |
12+
| **Performance** | 30% | P90 latency compared to the 30-day historical baseline |
13+
| **Stability** | 25% | Absence of anomalies and error spikes over the last 7 days |
14+
| **Quality** | 15% | Proportion of endpoints that are active and not degraded |
15+
16+
### Availability (30%)
17+
18+
```
19+
score = (2xx_requests / total_requests) × 100
20+
```
21+
22+
A 99% success rate gives a full 30 points. Below 95% the score drops sharply.
23+
24+
### Performance (30%)
25+
26+
Compares current P90 latency against the 30-day baseline:
27+
28+
- P90 at or below baseline → full 30 points
29+
- P90 10–30% above baseline → partial score
30+
- P90 more than 50% above baseline → 0 points on this dimension
31+
32+
### Stability (25%)
33+
34+
Counts anomaly events in the last 7 days (Z-score P99 spikes, sudden error rate increases). Each unresolved anomaly reduces the stability score.
35+
36+
### Quality (15%)
37+
38+
```
39+
score = (active_endpoints / total_endpoints) × 100
40+
```
41+
42+
An endpoint is considered "active and healthy" if it has received traffic in the last 21 days and has no open `PERF` insight.
43+
44+
## Reading the score
45+
46+
| Score | Status | Meaning |
47+
|---|---|---|
48+
| 85 – 100 | 🟢 Healthy | All systems nominal |
49+
| 65 – 84 | 🟡 Warning | One or more dimensions need attention |
50+
| 40 – 64 | 🟠 Degraded | Performance or availability issues detected |
51+
| 0 – 39 | 🔴 Critical | Significant problems requiring immediate action |

‎docs/features/insights.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Automatic Insights
2+
3+
Insights are plain-language alerts generated automatically from your traffic data — no dashboards to configure, no thresholds to set manually.
4+
5+
They appear in the dashboard's **Insights** panel and are recalculated on every flush cycle (default: every 60 seconds).
6+
7+
## Insight types
8+
9+
### ANOMALY
10+
11+
Detects statistically abnormal spikes in P99 latency using Z-score analysis.
12+
13+
> *"`GET /search` P99 latency is 8× above the 7-day average (current: 1240ms, normal: 148ms). Possible cause: dependency timeout or unusual traffic pattern."*
14+
15+
**Triggers when:** P99 latency exceeds the moving average by more than 3 standard deviations.
16+
17+
---
18+
19+
### DEAD
20+
21+
Identifies endpoints that have received no traffic for an extended period — safe candidates for deprecation.
22+
23+
> *"`DELETE /legacy/import` has received no requests in 23 days. Consider deprecating this endpoint."*
24+
25+
**Triggers when:** An endpoint has zero requests for the past **21 days** (configurable via `deadThresholdDays`).
26+
27+
---
28+
29+
### PERF / OK
30+
31+
Compares performance metrics before and after a deployment, when a `release` tag is configured.
32+
33+
> **PERF** — *"`POST /orders` P99 latency increased by 40% after deploying v1.3.0 (14h32 yesterday). Before: 230ms — After: 322ms."*
34+
35+
> **OK** — *"Deploy v1.4.0 (3 hours ago) introduced no detectable regression. Latency stable, error rate unchanged."*
36+
37+
**Triggers when:** A `release` value is set in the config and at least 30 minutes of post-deploy data is available.
38+
39+
See [Release Tracking](/features/release-tracking) for setup.
40+
41+
## How insights are prioritized
42+
43+
Insights are sorted by severity in the dashboard:
44+
45+
| Priority | Types |
46+
|---|---|
47+
| 🔴 Critical | `ANOMALY` with Z-score > 5, `PERF` regression > 50% |
48+
| 🟠 Warning | `PERF` regression 20–50%, `ANOMALY` Z-score 3–5 |
49+
| ⚫ Info | `DEAD` endpoints |
50+
| 🟢 Positive | `OK` (clean deploy confirmation) |
51+
52+
## Enabling release insights
53+
54+
Set the `release` option to activate `PERF` and `OK` insights:
55+
56+
```js
57+
app.use(apiforge({
58+
mode: 'local',
59+
release: process.env.npm_package_version, // e.g. '1.4.0'
60+
}))
61+
```
62+
63+
Each time the value changes (i.e. on a new deploy), APIForge creates a comparison baseline automatically.

‎docs/features/release-tracking.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Release Tracking
2+
3+
Release tracking automatically compares your API's performance before and after each deployment, giving you a clear answer to: *"Did this deploy make things better or worse?"*
4+
5+
## Setup
6+
7+
Pass the current version as the `release` option:
8+
9+
```js
10+
app.use(apiforge({
11+
mode: 'local',
12+
release: process.env.npm_package_version,
13+
}))
14+
```
15+
16+
Or hardcode it during the deploy process:
17+
18+
```js
19+
app.use(apiforge({
20+
mode: 'local',
21+
release: 'v1.4.0',
22+
}))
23+
```
24+
25+
::: tip Automate with environment variables
26+
Most CI/CD systems expose the version or git tag as an environment variable. Inject it at build time so it changes automatically on every deploy.
27+
:::
28+
29+
## How it works
30+
31+
1. When the `release` value **changes** (new deploy detected), APIForge records a baseline snapshot of the last 24h of metrics per endpoint.
32+
2. After **30 minutes** of post-deploy traffic, the engine compares new metrics against the baseline.
33+
3. A `PERF` or `OK` insight is generated for each endpoint with enough traffic.
34+
35+
## What is compared
36+
37+
| Metric | Compared |
38+
|---|---|
39+
| P50 latency | Before vs after |
40+
| P90 latency | Before vs after |
41+
| P99 latency | Before vs after |
42+
| Error rate (4xx + 5xx) | Before vs after |
43+
44+
## Example insights generated
45+
46+
```
47+
✅ OK v1.4.0 (deployed 3h ago) — No regression detected.
48+
Latency stable across 12 endpoints. Error rate unchanged.
49+
50+
⚠️ PERF POST /checkout — P99 +38% after v1.4.0
51+
Before: 210ms · After: 290ms
52+
Consider reviewing changes to the checkout handler.
53+
54+
✅ OK GET /products — P90 improved by 12% after v1.4.0
55+
Before: 85ms · After: 75ms
56+
```
57+
58+
## Requirements
59+
60+
- The `release` value must change between deploys (same value = no new baseline)
61+
- At least **100 requests** on an endpoint are needed for a statistically valid comparison
62+
- The comparison window is **30 minutes** minimum post-deploy

0 commit comments

Comments
 (0)