WeaveNote

Project identity

WeaveNote is a self-hosted notes and knowledge workspace. Repository work began April 3, 2026 and continued through July 17, 2026. The canonical recorded release is v4.4.18; the project corrected an earlier displayed 4.5.6 identity so the interface, package metadata, changelog, and deployment once again described the same artifact.

That version correction became a release-engineering lesson: a newer-looking number is not progress if it cannot be traced to an approved release.

Workspace capabilities

Architecture and stack

The Compose design separates PostgreSQL, the database viewer, and the WeaveNote application. Container isolation makes it possible to diagnose persistence, administration, and interface failures independently.

Knowledge model, deletion, and interaction

A note application is more than a text box. Ownership, notebook membership, graph relationships, ordering, timestamps, and deletion state must remain coherent across the editor, reader, search, graph, and administrative views.

• Soft deletion allows a trash workflow while keeping ordinary queries from returning removed notes.
• Cursor pagination avoids relying on unstable page numbers as records change.
• Autosave needs visible state, conflict handling, and failure recovery so the interface never promises a save that did not reach the server.
• The force graph is a consumer of the knowledge model, not the owner of it; graph data comes through a defined API.
• Import and export are part of data sovereignty and must preserve identifiers, relationships, text, and version compatibility.

AI synthesis with a deterministic fallback

WeaveNote supports optional synthesis workflows such as summarizing, expanding, and improving content. The design can use Claude, OpenAI, or Gemini when configured, while local deterministic processing can still produce tags and outlines without requiring a model provider.

• Provider keys stay on the server.
• Private notes should not leave the host unless the user deliberately enables and understands the configured provider.
• AI output is untrusted content: it requires review, safe rendering, and limits on prompt and response size.
• Feature availability should degrade cleanly when no AI provider is configured.

Authentication, JWT hardening, and roles

The release history records a critical security improvement: production refuses a missing or known-placeholder JWT signing secret. When no secret is supplied for the Docker deployment, the entrypoint generates a cryptographically random value and persists it for future container starts. This avoids both an insecure default and a surprise logout on every restart.

• JWT signing configuration fails closed instead of allowing a predictable development value into production.
• An authentication health endpoint verifies that tokens can actually be signed and validated; process health alone is insufficient.
• Role-based access distinguishes user, administrator, and super-administrator responsibilities.
• Every note and notebook operation still needs object-level ownership checks; a valid token does not authorize every record.
• Administrative viewers and routes remain private and should not be exposed merely because they run in Compose.

Database management, backup, and restoration

PostgreSQL and Prisma provide the durable knowledge layer. Schema changes belong in migrations, and the application should start only when the database is reachable and compatible. The database viewer is useful for controlled troubleshooting but must not become a shortcut around authorization.

Pipeline and troubleshooting lessons

A recorded Docker build failure exposed a subtle shell problem: installation output was piped through a tail command, so the pipeline returned the tail process's success code instead of the package installer's failure. The image appeared to advance while the real dependency error was hidden.

• Run dependency installation as a direct failing build step.
• Keep enough original output to diagnose resolution, network, lockfile, or native-build errors.
• Use lockfiles and consistent runtime versions so local and container dependency graphs agree.
• Build the production target before deployment; development success is not production proof.
• Make health checks depend on critical capabilities such as database and authentication readiness.

Versioning, preflight, and postflight

WeaveNote includes changelog and release documentation, deployment checklists, health guidance, scripts, examples, and tests. Together they turn a container restart into a traceable release.

The version shown in the UI must match the package, release notes, tag, running image, rollback instructions, and wiki article. That is the difference between a version label and version traceability.

What I learned and future roadmap

• Self-hosting creates data control only when backups, private administration, and restoration are designed as part of the app.
• Authentication configuration should fail closed, and its health check should exercise token behavior.
• RBAC and record ownership solve different authorization problems; both are required.
• AI should be optional, server-mediated, reviewable, and honest about which data leaves the host.
• Knowledge visualization works best as a modular view over stable data contracts.
• Release identity must be canonical across source, artifacts, interface, and operations.
• Container boundaries turn broad application failure into smaller, testable service failures.

Future work should deepen automated authorization tests, restore drills, note revision history, export compatibility checks, AI audit and redaction controls, accessibility testing for the graph, observability around autosave, and a release pipeline that produces signed, versioned images with a documented rollback.