Skip to content
jwillekePublic

About

A markdown based Next Generation Digital Platform

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

Β 

History

6,008 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

ngdpbase

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.

Features

  • 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.

Getting Started

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.

For Users

  1. Install dependencies:

    npm install
  2. Start the server:

    ./server.sh start          # Production mode (default)
    # or
    ./server.sh start dev      # Development mode
  3. 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)

For Developers

  • 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)

For AI Integration (MCP Server)

ngdpbase includes a Model Context Protocol (MCP) server for AI assistant integration:

# Build TypeScript
npm run build

# Start MCP server
npm run mcp

Integration 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.

Configuration

ngdpbase uses a hierarchical configuration system with three layers (later overrides earlier):

  1. config/app-default-config.json - Base defaults (required, ~1150 properties)
  2. config/app-{environment}-config.json - Environment-specific settings (optional)
    • Environment determined by NODE_ENV (development, production, test)
  3. config/app-custom-config.json - Local overrides (optional, persisted by admin UI)

Making Configuration Changes

Via Admin UI:

Manual Editing:

  • Edit config/app-custom-config.json directly

  • Restart server to apply changes:

    ./server.sh restart

Key Configuration Properties

{
  "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.

Operator Guides

For deploy-time and runtime operator topics see docs/admin/:

Project Structure

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

Examples

Creating a Page Link (JSPWiki Syntax):

[Link Text|PageName]  # Links to PageName with custom text
[PageName]           # Simple link to PageName

Inserting 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 image

Image 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)

Parser Architecture

ngdpbase uses a WikiDocument DOM extraction pipeline that provides robust, conflict-free parsing of JSPWiki syntax and Markdown:

How It Works

  1. Extract - JSPWiki syntax ([{$var}], [{Plugin}], [Link]) extracted before Markdown parsing
  2. Create DOM Nodes - WikiDocument DOM nodes created for each JSPWiki element
  3. Parse Markdown - markdown-it processes ALL Markdown without JSPWiki interference
  4. Merge - DOM nodes merged back into final HTML

Benefits

  • βœ… 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

Parser Configuration

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).

Documentation

Documentation

  • 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.

Version Management

This project follows Semantic Versioning (SemVer). Use the built-in version management tools:

Check Current Version

npm run version:show

Increment Version

npm 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)

Set Specific Version

npx tsx src/utils/version.ts set 1.2.3

Version Help

npm run version:help

The version management script automatically:

  • Updates the version in package.json, package-lock.json and config/app-default-config.json
  • Updates CHANGELOG.md with release information
  • Validates version format
  • Provides semantic versioning guidance

License

See LICENSE for details on usage and distribution.

About

A markdown based Next Generation Digital Platform

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages