# AGENTS.md - AI Assistant Context for JSS This document provides context for AI assistants working on JavaScript Solid Server (JSS). ## What is JSS? A lightweight Solid server implementation focused on simplicity and modern JavaScript. Alternative to Node Solid Server (NSS) and Community Solid Server (CSS). **Key differences from other Solid servers:** - Single-file JSON-LD storage (no quad stores) - Content negotiation converts JSON-LD ↔ Turtle on the fly - Built on Fastify (not Express) - Uses oidc-provider for identity - Supports Nostr NIP-98 authentication (unique to JSS) ## Architecture ``` src/ ├── server.js # Fastify setup, route registration ├── handlers/ # LDP operations (GET, PUT, POST, PATCH, DELETE) │ ├── resource.js # File operations │ └── container.js # Directory operations, pod creation ├── auth/ # Authentication │ ├── middleware.js # WAC authorization hook │ ├── solid-oidc.js # DPoP token verification │ ├── nostr.js # NIP-98 Schnorr signatures │ └── token.js # Simple Bearer tokens ├── idp/ # Identity Provider (oidc-provider) │ ├── provider.js # OIDC configuration │ ├── interactions.js # Login/consent UI handlers │ └── accounts.js # User account storage ├── wac/ # Web Access Control │ ├── checker.js # Permission checking │ └── parser.js # ACL file parsing/generation ├── rdf/ # RDF handling │ ├── conneg.js # Content negotiation │ └── turtle.js # Turtle ↔ JSON-LD conversion ├── notifications/ # WebSocket real-time updates │ ├── websocket.js # solid-0.1 protocol handler │ └── events.js # Event emitter for changes ├── ldp/ # Linked Data Platform │ ├── headers.js # LDP response headers │ └── container.js # Container JSON-LD generation └── storage/ # File system operations └── filesystem.js # Read/write/stat/list ``` ## Key Design Decisions ### JSON-LD as canonical storage All RDF is stored as JSON-LD. When clients request Turtle, we convert on the fly. This simplifies storage and allows non-RDF tools to read the data. ### HTML profiles with JSON-LD data islands WebID profiles are HTML documents with embedded `