PaperTrail is a lightweight visual evidence board for organizing ideas, documents, images, and links. It lets you pin down pieces of information, connect them freely, and uncover patterns. Whether you’re researching, investigating, or just making sense of complex projects, PaperTrail helps you create a clear trail of evidence you can return to and share.
We use Node.js/Express with the Handlebars template engine as the core stack for this application. SQLite serves as the primary database, with straightforward extensibility to PostgreSQL (or any other SQL database) through Prisma.
All uploaded assets are stored under /data/uploads/*, organized by board IDs.
Portability is currently managed via the Import/Export functionality.
You can allow frictionless exploration via a guest account.
Use following environment variables as feature toggles (set in .env):
GUEST_LOGIN_ENABLED=true|false
GUEST_LOGIN_ENABLED_BYPASS_LOGIN=true|false
Behavior:
GUEST_LOGIN_ENABLED=false→ Normal auth only (default).GUEST_LOGIN_ENABLED=trueandGUEST_LOGIN_ENABLED_BYPASS_LOGIN=false→ Login page shows a “Continue as guest” link. Each click creates a fresh random guest (handler likeguest_ab12cd34).GUEST_LOGIN_ENABLED=trueandGUEST_LOGIN_ENABLED_BYPASS_LOGIN=true→ No login screen. First visitor creates (or reuses) a singleton guest (handlerguest); all users share that session pattern (until cookie expires).
Notes:
- Guest boards you create are still tied to the guest user id.
- Disable in production if multi‑user accountability is required.
A public demo board (“Sri Lanka Protests — 2022”) is embedded in prisma/seed.mjs.
It is inserted only if it does not already exist (non‑destructive).
Run the seed after pushing the schema:
npx prisma db push
node prisma/seed.mjs
# or if configured:
npx prisma db seed // or npm run prisma:seedForce re-seed (optional):
sqlite3 data/papertrail.db "DELETE FROM boards WHERE id='board-sri-lanka-protests-2022';"
node prisma/seed.mjsIf you later bump the board JSON format, also update:
schemaVersioninseed.mjsschemaVersionconstant inpackage.json
git clone [email protected]:kasunben/PaperTrail.git
cd PaperTrail
cp .env.example .env
npm iSync Databse with Prisma schema.
npx prisma db pushUse npm run dev to launch the development server with automatic file watching. For the production build, use npm start.
We use Prisma as intermediate abstraction layer between the app code and the database.
- Update
prisma/schema.prismafirst - Run
npx prisma formatto ensure the validity and format the schema changes - Run the migration command to log the change with
npx prisma migrate dev --name <migration-name-in-snake-case>
We follow a Git Flow inspired branching strategy to keep development organized and production stable.
Branches
main→ production branch (always deployable).develop→ integration branch (latest development work).feat/→ short-lived branches for new features or fixes.release/→ optional branches to prepare a release.hotfix/→ urgent fixes branched from main.fix/→ bug fixes branched from develop.chore/→ maintenance tasks (docs, tooling, dependencies, CI), no product changes.
git switch -c feat/my-feature developWork, commit, and rebase with develop to stay updated.
- Use Squash & Merge to keep history clean.
- When develop is stable:
git checkout main
git merge --ff-only develop
git push origin mainAlternatively:
git fetch origin
git checkout develop
git pull # update local develop
git rebase origin/main # replay develop on top of main
# resolve any conflicts, then:
git push --force-with-lease
git checkout main
git merge --ff-only develop
git push- Tag the release:
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin v1.2.0- Branch from
main, fix, then merge back into bothmainanddevelop.
Notes:
- Do not rebase shared branches (
main,develop).- Rebase your local feature branches before opening a PR to keep history linear.
- Squash merges ensure each feature is a single, clean commit in history.
The community version licensed under MIT.