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)

RouteBeschrijvingFormaat
/helpHome-pagina met overzichtHTML
/help/faqVeelgestelde vragen, categorienHTML + JSON
/help/docsDocumentatie-artikelenMarkdown → HTML
/help/docs/:slugSpecifiek artikelMarkdown → HTML
/help/searchZoekresultatenJSON
/help/feedbackFeedback-formulierForm → POST
/help/contactContactinformatie + kanalenHTML
/help/changelogVersiegeschiedenisMarkdown → HTML

3. FAQ structuur

CategorieVoorbeelden
Getting StartedWat is MAOS? Hoe installeer ik een DApp? Hoe verbind ik mijn wallet?
WalletHoe stort ik funds? Hoe onderteken ik een transactie? Wat is een session key?
DAppsHoe installeer ik een DApp? Hoe更新 ik een DApp? Hoe verwijder ik een DApp?
SecurityHoe beheer ik permissies? Wat is een launch grant? Hoe bescherm ik mijn keys?
TroubleshootingDApp 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

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

VeldTypeVerplicht
typeenum (bug, feature, question, other)Ja
subjectstring (max 100 tekens)Ja
messagestring (max 2000 tekens)Ja
emailstring (optioneel, voor terugkoppeling)Nee
versionstring (automatisch, huidige versie)Automatisch
logsboolean (optioneel, debug-logs meesturen)Nee

6. Contact-kanalen

KanaalBeschrijvingReactietijd
DiscordCommunity support, snelle vragenRealtime
GitHub IssuesBug reports, feature requests1-3 dagen
EmailSecurity reports, formele zaken3-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-typeLimietWindow
GET /help/*60 req/min60s
GET /help/search30 req/min60s
POST /help/feedback5 req/min60s
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

10. Risico's en aanbevelingen

RisicoImpactMitigatie
Content outdatedGemiddeldVersiebeheer + automatische checks + community corrections
Search misbruikGemiddeldRate-limiting + query-limiet + cache
Feedback spamGemiddeldRate-limiting + CAPTCHA (indien nodig)
Performance bij grote contentGemiddeldIndexering + 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.