System-apps help
Help-DApp (Tier-0) • direct in shell • FAQ, docs, search, feedback, contact, changelog • read-only routes • rate-limiting • status: ontwerp, nog geen code
Kerndefinitie: De Help-DApp is een Tier-0 systeemapplicatie die direct in de shell draait. Het biedt centrale documentatie, FAQ, zoekfunctionaliteit, feedback-mogelijkheden en changelog. Alle routes zijn read-only, met rate-limiting om misbruik te voorkomen.
1. Architectuur
┌─────────────────────────────────────────────────┐
│ Shell (Tier-0) │
│ ┌─────────────────────────────────────────┐ │
│ │ Help-DApp (direct) │ │
│ │ ┌─────────────────────────────────┐ │ │
│ │ │ FAQ (Veelgestelde vragen) │ │ │
│ │ └─────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────┐ │ │
│ │ │ Documentatie (docs) │ │ │
│ │ └─────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────┐ │ │
│ │ │ Search (zoekfunctie) │ │ │
│ │ └─────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────┐ │ │
│ │ │ Feedback (formulier) │ │ │
│ │ └─────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────┐ │ │
│ │ │ Contact (supportkanalen) │ │ │
│ │ └─────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────┐ │ │
│ │ │ Changelog (versiegeschiedenis) │ │ │
│ │ └─────────────────────────────────┘ │ │
│ └─────────────────────┬───────────────────┘ │
│ │ VAPI (read-only) │
│ ┌─────────────────────┴───────────────────┐ │
│ │ Content Store │ │
│ │ (Markdown + versiebeheer) │ │
│ └─────────────────────┬───────────────────┘ │
│ │ │
│ ┌─────────────────────┴───────────────────┐ │
│ │ Rate Limiter │ │
│ │ (token bucket, per sessie) │ │
│ └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
2. Routes (alleen lezen)
| Route | Beschrijving | Formaat |
/help | Home-pagina met overzicht | HTML |
/help/faq | Veelgestelde vragen, categorien | HTML + JSON |
/help/docs | Documentatie-artikelen | Markdown → HTML |
/help/docs/:slug | Specifiek artikel | Markdown → HTML |
/help/search | Zoekresultaten | JSON |
/help/feedback | Feedback-formulier | Form → POST |
/help/contact | Contactinformatie + kanalen | HTML |
/help/changelog | Versiegeschiedenis | Markdown → HTML |
3. FAQ structuur
| Categorie | Voorbeelden |
| Getting Started | Wat is MAOS? Hoe installeer ik een DApp? Hoe verbind ik mijn wallet? |
| Wallet | Hoe stort ik funds? Hoe onderteken ik een transactie? Wat is een session key? |
| DApps | Hoe installeer ik een DApp? Hoe更新 ik een DApp? Hoe verwijder ik een DApp? |
| Security | Hoe beheer ik permissies? Wat is een launch grant? Hoe bescherm ik mijn keys? |
| Troubleshooting | DApp laadt niet, transactie faalt, synchronisatie-problemen |
3.1 FAQ item structuur
{
"id": "faq-001",
"category": "Getting Started",
"question": "Wat is MAOS?",
"answer": "MAOS is een decentralized operating system dat...",
"tags": ["intro", "basics"],
"related": ["faq-002", "faq-003"],
"lastUpdated": "2026-01-16T14:20:00Z"
}
4. Search-functionaliteit
- Trefwoord: Zoek op volledige tekst in FAQ + docs + changelog.
- Categorie: Filter op categorie (FAQ) of sectie (docs).
- Tags: Filter op tags voor gerelateerde content.
- Relevantie: Resultaten gesorteerd op relevantie (BM25-scoring).
- Autocomplete: Suggesties tijdens het typen.
Search flow:
│
├── 1. Gebruiker voert zoekterm in
│ │
│ └── Autocomplete: suggesties na 2+ tekens
│
├── 2. Zoekopdracht (minimaal 2 tekens)
│ │
│ ├── Rate-limit check (token bucket)
│ │
│ └── BM25 search over content
│ ├── FAQ items
│ ├── Docs artikelen
│ └── Changelog entries
│
├── 3. Resultaten
│ │
│ └── Gesorteerd op relevantie + filters
│
└── 4. Resultaat aanklikken
└── Navigatie naar specifieke pagina
5. Feedback-formulier
| Veld | Type | Verplicht |
type | enum (bug, feature, question, other) | Ja |
subject | string (max 100 tekens) | Ja |
message | string (max 2000 tekens) | Ja |
email | string (optioneel, voor terugkoppeling) | Nee |
version | string (automatisch, huidige versie) | Automatisch |
logs | boolean (optioneel, debug-logs meesturen) | Nee |
6. Contact-kanalen
| Kanaal | Beschrijving | Reactietijd |
| Discord | Community support, snelle vragen | Realtime |
| GitHub Issues | Bug reports, feature requests | 1-3 dagen |
| Email | Security reports, formele zaken | 3-5 dagen |
7. Changelog
Changelog structuur:
│
├── Versie (semver)
│ ├── Datum
│ ├── Added (nieuwe features)
│ ├── Changed (wijzigingen)
│ ├── Fixed (bugfixes)
│ └── Removed (verwijderde features)
│
└── Versiebeheer:
├── Laatste 10 versies zichtbaar
├── Volledige historie via paginering
└── Filter op type wijziging
8. Rate-limiting
BESLIST: Alle routes zijn read-only. Rate-limiting via token bucket per sessie. Feedback-formulier heeft aparte limiet om spam te voorkomen.
| Route-type | Limiet | Window |
GET /help/* | 60 req/min | 60s |
GET /help/search | 30 req/min | 60s |
POST /help/feedback | 5 req/min | 60s |
Rate-limit flow:
│
├── 1. Request binnen
│ │
│ └── Rate-limit check (token bucket per sessie)
│
├── 2. Toegestaan?
│ │
│ ├── Ja → verzoek verwerken + response
│ │
│ └── Nee → 429 Too Many Requests
│ │
│ └── Headers: Retry-After, X-RateLimit-Remaining
9. Acceptatiecriteria
- Help-DApp draait direct in shell, niet in iframe.
- Alle routes zijn read-only (geen writes behalve feedback POST).
- FAQ, docs, search, feedback, contact, changelog bereikbaar.
- Search werkt met BM25-scoring + autocomplete.
- Rate-limiting op alle routes (token bucket per sessie).
- Feedback-formulier met validatie + rate-limiting.
- Changelog met versiebeheer + filter op type wijziging.
10. Risico's en aanbevelingen
| Risico | Impact | Mitigatie |
| Content outdated | Gemiddeld | Versiebeheer + automatische checks + community corrections |
| Search misbruik | Gemiddeld | Rate-limiting + query-limiet + cache |
| Feedback spam | Gemiddeld | Rate-limiting + CAPTCHA (indien nodig) |
| Performance bij grote content | Gemiddeld | Indexering + paginering + lazy loading |
11. Verwijzingen naar verwante specs
Volgende stap Na akkoord: Help-DApp UI + FAQ-structuur + docs-content + search-index + feedback-formulier + changelog-implementatie + rate-limiting.