A general-purpose, file-based platform for pages, files and records, built with Node.js, Express, TypeScript and Markdown. Its page syntax was inspired by JSPWiki. Add-ons build on it (health records, accounting, an association's units and owners, calendars, forms).
π See docs/planning/ROADMAP.md for project vision and priorities.
- Pages stored as Markdown files, with JSPWiki-style links, categories and keywords, red links for missing pages, and full version history (diff, compare, restore)
- Private and encrypted vaults: a user's own pages and files, optionally encrypted, shareable by link
- Files and media: attachments, a shared file pool, a media library with thumbnails
- Import: a user-facing import screen and engine (
/import) with add-on converters ("shims") and receivers, duplicate detection and kept originals - Users and sign-in: passwords, passkeys, outside sign-in (OIDC), recovery words, step-up for sensitive actions, proxy access (acting for another user), agent tokens
- Identities: users and contacts with identity records, organizations and affiliations β terms defined in docs/GLOSSARY.md
- Policy-based access control: permissions and roles as configuration, decided in one place (PDP/PIP), page audiences and access rules
- Audit trail: every security-relevant action recorded, tamper-evident chain
- Consent: terms and privacy documents with versions; users accept, with a banner when terms change
- Add-ons: a host API, manifest, own databases (encrypted when personal), profile sections, background jobs
- Backups: whole-site backup and staged restore
- Admin dashboard: users, roles, contacts, configuration, jobs, maintenance mode
- π€ Model Context Protocol (MCP) server for AI assistants (Claude Desktop, Claude Code): search and read content and metadata
π Detailed technical documentation available in docs/ folder.
There are three ways to run ngdpbase β a direct install from a clone, a container from the published image, or Kubernetes. Add-ons are bundled, or installed from npm through the site's configuration; no image of your own is needed. docs/installation/Implementation.md is the lead document: it says what each method inherits from this repository and where its environment and configuration live. The steps below are the direct install.
-
Install dependencies:
npm install
-
Start the server:
./server.sh start # Production mode (default) # or ./server.sh start dev # Development mode
-
Open your browser and navigate to
http://localhost:3000
Server Management:
./server.sh start [dev|prod] # Start server (default: production)
./server.sh stop # Stop server
./server.sh restart [dev|prod] # Restart server
./server.sh status # Show server status
./server.sh logs [50] # Show logs (default: 50 lines)
./server.sh env # Show environment config
./server.sh unlock # Remove PID lock (if server crashed)- Follow the setup steps above
- The codebase uses TypeScript with strict mode enabled
- Read CONTRIBUTING.md for coding standards, TypeScript guidelines, and contribution guidelines
- Check CHANGELOG.md for version history and migration notes
TypeScript Commands:
npm run typecheck # Type checking (no output)
npm run build # Build TypeScript to JavaScript
npm run build:watch # Watch mode for development
npm test # Run all tests (supports .ts and .js)ngdpbase includes a Model Context Protocol (MCP) server for AI assistant integration:
# Build TypeScript
npm run build
# Start MCP server
npm run mcpIntegration with Claude Desktop:
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"ngdpbase": {
"command": "node",
"args": ["/path/to/ngdpbase/dist/mcp-server.js"],
"cwd": "/path/to/ngdpbase"
}
}
}π See docs/MCP-SERVER.md for complete documentation.
ngdpbase uses a hierarchical configuration system with three layers (later overrides earlier):
config/app-default-config.json- Base defaults (required, ~1150 properties)config/app-{environment}-config.json- Environment-specific settings (optional)- Environment determined by
NODE_ENV(development, production, test)
- Environment determined by
config/app-custom-config.json- Local overrides (optional, persisted by admin UI)
Via Admin UI:
- Navigate to /admin/configuration
- Changes saved to
app-custom-config.json - Restart required: /admin/restart
Manual Editing:
-
Edit
config/app-custom-config.jsondirectly -
Restart server to apply changes:
./server.sh restart
{
"ngdpbase.application-name": "ngdpbase",
"ngdpbase.server.port": 3000,
"ngdpbase.base-url": "http://localhost:3000",
"ngdpbase.front-page": "Welcome",
"ngdpbase.page.provider": "filesystemprovider",
"ngdpbase.backup.auto-backup": true
}Note: Properties starting with _ are treated as comments and ignored.
For deploy-time and runtime operator topics see docs/admin/:
- Self-Registration β disable the public
/registerform - Email Setup β outbound mail (magic-link login, contact form)
- Backups β backup configuration
- Telemetry β metrics and observability
- Versioning Deployment Guide β page-versioning storage layout
ngdpbase/
βββ src/ # Source code
β βββ core/ # Core engine components
β βββ managers/ # 30 domain-specific managers
β βββ plugins/ # Auto-discovered plugin modules
β βββ providers/ # Storage provider implementations
β βββ parsers/ # WikiDocument DOM parser
β β βββ dom/ # DOM handlers and WikiDocument
β β βββ __tests__/ # Parser test suites
β βββ routes/ # HTTP route handlers
β βββ types/ # Shared TypeScript interfaces
β βββ utils/ # Utility functions
βββ addons/ # Domain addon packages (calendar, forms, journal, elasticsearch)
βββ config/ # Application configuration
β βββ app-default-config.json # Base defaults (~1150 properties)
β βββ app-{env}-config.json # Environment-specific
β βββ app-custom-config.json # Local overrides
βββ public/ # Static assets (CSS, JS, images)
βββ views/ # EJS templates
βββ docs/ # Documentation
β βββ architecture/ # System architecture docs
β βββ development/ # Development guides
β βββ planning/ # Project planning docs
β βββ api/ # API documentation
β βββ migration/ # Migration guides
β βββ testing/ # Testing documentation
β βββ managers/ # Manager documentation
βββ scripts/ # Utility scripts
βββ templates/ # Page templates
βββ themes/ # UI themes
βββ required-pages/ # System pages seeded on first boot
βββ data/ # All instance-specific runtime data
β βββ pages/ # User-created pages
β βββ users/ # User accounts and profiles
β βββ attachments/ # Uploaded file storage
β βββ backups/ # System backups (BackupManager)
β βββ logs/ # Application logs
β βββ sessions/ # Express session store
β βββ search-index/ # Search index files
βββ exports/ # Exported content
βββ reports/ # Test coverage reports
βββ coverage/ # Istanbul coverage dataπ Detailed project structure documentation available in docs/architecture/PROJECT-STRUCTURE.md
Creating a Page Link (JSPWiki Syntax):
[Link Text|PageName] # Links to PageName with custom text
[PageName] # Simple link to PageNameInserting Images (JSPWiki Plugin Syntax):
[{Image src='image.jpg' alt='Description' width='300'}] # Basic image
[{Image src='/images/photo.jpg' alt='Photo' height='200'}] # With height
[{Image src='https://example.com/image.png' class='responsive'}] # External imageImage Upload:
- Use the image upload section in the page editor
- Select an image file and click "Upload Image"
- Click "Insert at Cursor" to add the image to your content
- Supported formats: JPEG, PNG, GIF, WebP (max 5MB)
ngdpbase uses a WikiDocument DOM extraction pipeline that provides robust, conflict-free parsing of JSPWiki syntax and Markdown:
- Extract - JSPWiki syntax (
[{$var}],[{Plugin}],[Link]) extracted before Markdown parsing - Create DOM Nodes - WikiDocument DOM nodes created for each JSPWiki element
- Parse Markdown - markdown-it processes ALL Markdown without JSPWiki interference
- Merge - DOM nodes merged back into final HTML
- β No parsing conflicts - JSPWiki and Markdown processed independently
- β
Correct heading rendering - All Markdown headings (
##,###) render properly - β
Natural escaping -
[[{$var}]]creates literal text via DOM nodes - β Extensible - Easy to add custom syntax via DOM handlers
- β Production-ready - 376+ tests with 100% success rate
The WikiDocument DOM parser is enabled by default. To use the legacy parser, add to config/app-custom-config.json:
{
"jspwiki.parser.useExtractionPipeline": false
}Then restart the server (see Configuration section above).
- API Reference: docs/api/MarkupParser-API.md
- Migration Guide: docs/migration/WikiDocument-DOM-Migration.md
- Architecture: docs/architecture/WikiDocument-DOM-Architecture.md
- docs/installation/Implementation.md - The four ways to run ngdpbase and what each inherits; the lead installation document.
- CHANGELOG.md - Version history and detailed change notes.
- RELEASES.md - Publishing contract for downstream consumers (geohazardwatch, mj-infra-flux, etc.) β what ngdpbase publishes, when, and where.
- CONTRIBUTING.md - How to contribute to the project.
- ROADMAP.md - Project vision and feature priorities.
- docs/ - In-depth technical guides on architecture, plugins, and more.
This project follows Semantic Versioning (SemVer). Use the built-in version management tools:
npm run version:shownpm run version:patch # Bug fixes (1.2.0 β 1.2.1)
npm run version:minor # New features (1.2.0 β 1.3.0)
npm run version:major # Breaking changes (1.2.0 β 2.0.0)npx tsx src/utils/version.ts set 1.2.3npm run version:helpThe version management script automatically:
- Updates the version in
package.json,package-lock.jsonandconfig/app-default-config.json - Updates
CHANGELOG.mdwith release information - Validates version format
- Provides semantic versioning guidance
See LICENSE for details on usage and distribution.