What It Does
Iokeep is a full-stack note-taking application built as two services: a Next.js frontend and an Express API. Authenticated users organize notes into folders, write with a Lexical rich-text editor, sort note lists, and publish individual notes for read-only sharing.
The editor supports h1–h3 headings, bold, italic, underline, undo, and redo. After one second without a content change, a custom Lexical plugin persists the serialized editor state and the first two non-empty lines used as the note-list preview.
The project remains under active development. It is a useful end-to-end engineering case study, not an offline-first or collaborative editor today.
Frontend Architecture
The frontend runs on Next.js 15 and React 19 using the App Router. Feature directories separate the editor, note manager, folder manager, authentication forms, navigation, and profile behavior.
AutoSyncPlugin models editing as a dirty-to-idle transition rather than saving on every keystroke. It ignores the initial empty editor state, avoids creating blank notes, and chooses between two API paths:
- no selected note plus a selected folder → create a note;
- selected note ID → update that note.
On successful creation, the returned ID becomes the selected note so later saves use PATCH rather than creating duplicates. SWR manages folder and note reads; successful mutations update the relevant client cache.
Browser calls use /be/... URLs. A Next.js rewrite proxies them to the environment-specific Express service, keeping the backend address out of feature components and preserving a same-origin browser boundary for cookies.
For a deeper look at this lifecycle, see Autosave Is a State Machine.
Backend Architecture
The API uses Express, TypeScript, PostgreSQL, Prisma, and three feature areas: authentication, folders, and notes.
The backend originally used MongoDB and Mongoose directly from services. I replaced that persistence layer with repository interfaces and Prisma implementations:
Controller → Service → Repository interface → Prisma → PostgreSQLServices depend on plain TypeScript contracts. A composition root selects the concrete user, folder, and note repositories. Response mappers preserve _id in the HTTP API while PostgreSQL uses UUID id columns internally.
The relational schema adds foreign keys, cascading deletes from users to folders and folders to notes, and a composite uniqueness constraint for folder names per owner. Folder note counts use one grouped query instead of a per-folder count loop.
The full migration write-up is in Migrating Iokeep from MongoDB to PostgreSQL.
Authentication and Sessions
Passwords are hashed with bcrypt. Login signs access and refresh JWTs and places both in HttpOnly cookies. The backend stores issued refresh tokens for server-side invalidation, and logout removes the current token before clearing both cookies.
Next.js middleware protects the /app/* route area by checking the refresh token with the backend. The API middleware verifies the access-token cookie before guarded mutations.
This is not refresh-token rotation: login issues and stores a token, access-token renewal reuses it, and logout invalidates it. A future session-table design would provide better device tracking, expiry management, and revocation history.
Verification
The two repositories include complementary boundary tests:
- a Playwright onboarding journey covering signup, login, folder creation, and note creation in the browser;
- an HTTP integration suite that boots Express on an ephemeral port, talks to PostgreSQL, maintains an authentication cookie jar, and exercises health, auth, folder, note, and logout flows;
- an OpenAPI specification describing the current backend contract.
Engineering Trade-offs and Remaining Work
- Lexical JSON is the canonical document format. It hydrates the editor directly and preserves formatting, but it needs document versioning before node schemas evolve.
- Autosave is remote-first. There is no IndexedDB queue, offline retry, CRDT, or conflict-resolution layer yet.
- Sync state needs more precision. The UI currently distinguishes only syncing from not syncing; failed, dirty, retrying, and offline states should be explicit.
- Authorization needs hardening. Cookie authentication exists, but comprehensive resource-owner checks are a release requirement for folder and note operations.
- API errors need normalization. Some domain failures still use HTTP 200 or 500 where clearer 4xx semantics would be more appropriate.
What I Learned
Iokeep forced me to work across the boundaries that make a full-stack feature reliable:
- translating editor lifecycle events into persistence decisions;
- keeping rich document state and lightweight previews coherent;
- preserving a client contract while replacing the database underneath it;
- designing repository seams instead of letting ORM types spread through services;
- testing authentication and CRUD behavior through real HTTP requests and browser flows;
- separating implemented behavior from future architecture.
The result is not a claim that every platform concern is solved. It is a concrete record of how the system evolved, the trade-offs behind it, and the next failure modes I would address.