How amatiasq/pensieve works
Main Components
• User Interface (UI) / Frontend
– Represented mainly by the “src/5-app”, “src/7-components”, and “index.html”.
– Contains the React-based routes (e.g., CreateNote, EditNote, EditSettings) and global contexts.
– Incorporates the Monaco Editor (in “src/7-components/Editor” and its monaco extensions) for sophisticated text editing.
• Business Logic / Core Services
– Lives in folders “src/0-dom” (DOM utilities), “src/1-core” (services such as message bus, HTTP helper, event handlers like busy-indicator, keyboard, mouse, URL handling).
– Implements various application helpers that “glue” UI events with data processing.
• Domain Entities
– Found under “src/2-entities” (Note, Settings, Shortcuts).
– These encapsulate the core data models of the application.
• GitHub Integration
– This layer handles communication with GitHub, ensuring changes in notes are recorded as Git commits.
• Storage & Middleware Layer
– The “src/4-storage” directory is a dedicated storage layer that abstracts how data is saved and fetched.
– Multiple middleware components (such as CachedStore, ForageStore, GHRepoStore, MixedStore, and ResilientOnlineStore) wrap the storage mechanism, handling local (and possibly remote) caching and ensuring resiliency.
– This layer coordinates with both local persistence and remote storage (synchronizing with GitHub).
• API Endpoints / Serverless Functions
– Separate API functional code can be seen in “src/api”—this folder likely encapsulates endpoints (or “wrangler.toml” indicates possible Cloudflare Worker deployment) for handling auth, commit actions, etc.
– It plays a supporting role to the frontend, ensuring integration with services.
• Testing & DevOps
– The “cypress” folder denotes end-to-end tests.
– CI/CD workflows are defined in “.github/workflows/ci.yml”.
– Tools like ESLint and Prettier (with their respective config files) ensure code consistency.
– Vite is configured via “vite.config.ts” and project-specific TypeScript settings are in “tsconfig.json”.
Relationships and Interactions
– UI components communicate with the business logic via React Hooks (see “src/6-hooks”), which abstract many behaviors like note creation, navigation, or settings updates.
– The business logic uses domain entities to model data and then interacts with the storage layer (src/4-storage) for both local caching and remote persistence.
– The GitHub integration layer sits between the note operations and remote storage, converting note updates into Git operations (commits, branch updates, etc.) and handling user authentication.
– The API layer (in “src/api”) might serve as a gateway for some operations, bridging the gap between the UI and GitHub backend if needed.
– There are also utility layers (DOM and other utilities in “src/util”) that support the core functions and debugging.
Architectural Patterns and Principles
– Modular layering: Separation of concerns is clear from UI, business logic, domain models, storage, and external integrations.
– Middleware and cascading store mechanisms in the storage layer allow combining local and remote data strategies.
– React’s component architecture paired with hooks provides decoupled state management and user interaction handling.
– Integration with external APIs (GitHub) is abstracted into a dedicated layer, allowing for easier future extension or mock/testing.
Relevant Technologies
• Frontend: React (function components, hooks), TypeScript, Vite, Monaco Editor.
• Testing: Cypress for end-to-end tests.
• GitHub APIs: REST and GraphQL clients.
• CI/CD: GitHub Actions (defined in “.github/workflows”).
• Package managers: Bun and npm (package.json, bun.lockb, etc.)
• Build and code style tooling: ESLint, Prettier, Visual Studio Code configs.
Overall Focus
– Don’t hesitate to break down the middleware storage layer into multiple components if it aids clarity.