chaifeng / doughnut

Learning aide, note taking, team learning, etc.

Doughnut

About

Doughnut is a Personal Knowledge Management (PKM) tool combining zettelkasten style of knowledge capture with some features to enhance learning (spaced-repetition, smart reminders) and ability to share knowledge bits with other people (for buddy/team learning).

For more background info you can read::

• Scholarship & Learning
• Knowledge Acquisition & Documentation Structuring

Product Backlog

Story Map

Doughnut Technology Stack

Current Architecture Videos

Getting started

1. Quick Start - doughnut development environment setup

🏁 From the root of doughnut directory, in a terminal, run:

Please ensure your git configuration is appropriate for your OS to respect the correct line endings:

• macOS/Linux run git config --global core.autocrlf input then git add --renormalize .
• Microsoft Windows git config --global core.autocrlf true then git add --renormalize .

./setup-doughnut-dev.sh

Ensure your OS (WSL2/Ubuntu/Fedora, etc) has /bin/sh point to bash. If you are using Ubuntu where /bin/sh is symlinked to dash, please run sudo dpkg-reconfigure dash and answer "No" to reconfigure to bash as default.

🪟 WSL2 with WSLg: Additional things to note for Microsoft Windows10/Windows11 developers using WSL2g with Ubuntu-22.04.

⚠️ Nix and sdkman don't play very well together. A simple way around is to move or rename ~/.sdkman dir and comment out sdkman related config in ~/.<SHELL>rc.

🚦 🚧 ONLY if you hit problems with the above quick-start setup, you should manually walk through the local development environment nix setup.

2. Setup and run doughnut with migrations in 'E2E' profile (backend app started on port 9081)

From the root of your doughnut directory, start your doughnut nix development environment with

nix develop

dum i && dum frontend:build && dum sut

• Rerun it each time you reset the database.

2.1 Run full backend unit tests suite from terminal/CLI

• From doughnut source root directory:

dum backend:test

3. IntelliJ IDEA settings

4. End-to-End Test / Features / Cucumber / SbE / ATDD

We use cucumber Gherkin + cypress (test driver) Javascript/Typescript framework to drive the end-to-end test suite.

• Cucumber

The Cypress+Cucumber tests are in JavaScript/TypeScript.

cypress

• cypress-cucumber-preprocessor

Commands

For MS Windows WSL2 users:

1. you need to ensure your WSL2 Linux has xvfb installed manually before you can run cypress. This is not managed by Nix!
2. export NODE_OPTIONS="--max-old-space-size=4096" before running any cypress related commands ( e.g. cy:open or cy:run).

Purpose	Command (run from doughnut source root directory)
Install needed e2e tooling	dum i
Start SUT (backend system under test)	dum sut (starts backend SUT ONLY)
Start Mock for external backend	dum start:mb (starts mocked external backend ONLY)
Start only the Cypress IDE	dum cy:open (starts Cypress IDE ONLY)
Run all e2e test	dum t (compile frontend assets, start backend SUT, mountebank virtual service provider & cypress headless e2e testing)
Run cypress IDE	dum test:open (starts frontend SUT in HMR mode, backend SUT, mountebank virtual service provider & cypress IDE)
Generate TypeScript Interfaces	dum generateTypeScript (Generate TypeScript Interfaces from backend JSON classes. Should run manually every time backend JSON class changes)

Structure

Purpose	Location
feature files	cypress/e2e/*.feature
step definitions	cypress/step_definitions/*.ts
custom DSL	cypress/support/*.ts
cucumber hooks	cypress/step_definitions/common/hook.ts
test fixtures	cypress/fixtures/*.*
cypress config	cypress/config/*.json
cypress plugins	cypress/plugins/index.ts

5. Database migrations

You can find the database migrations in backend/src/main/resources/db.migration/. The migrations are run automatically when the backend app starts up. It will also run the migrations for test when you run dum backend:test. To trigger the test DB migration manually, run backend/gradlew testDBMigrate.

6. Vue3 web-app frontend

We chose Vue3 + Vite to build our frontend.

How-to

Run frontend unit tests (with Vitest)

From doughnut source root directory

dum frontend:test

Run frontend web-app (app will launch on port 5173)

dum frontend:sut

Build & Bundle Vue3 frontend web-app assets and startup backend app (backend webapp will launch on port 9081).

dum frontend:build
dum sut

Expect to find minified and uglified web bundle assets in backend/src/main/resources/static directory:

❯ pwd
/home/lia/doughnut/backend/src/main/resources/static
❯ tree -L 3
.
├── assets
│   ├── main.32137c85.js
│   ├── main.b097c993.css
│   └── vendor.8f9eb49d.js
├── index.html
├── odd-e.ico
└── odd-e.png

1 directory, 6 files

7. Style Guide & Code linting/formating

8. Production environment

9. Doughnut source code secrets management

How to Contribute

• We welcome product ideas and code contribution.
• Collaborate over:
  • GitHub Discussions for product ideas/features,
  • GitHub Issues for reporting issues or bugs, OR
  • doughnut gitter.im
• FOSS style; Fork and submit GitHub PR.
  • Please keep the PR small and on only one topic
  • The code need to come with tests