ℹ️ This section provides more detail if you are interested in the internal workings of the Herda apps. If you do not need that much detail, head back to the README.
Herda, as a project, comes in three parts:
- MongoDB database
- Headless server app
- Progressive web app
The PWA connects to the server, which in turn connects to the database.
The server app is built in Node.js with TypeScript and has minimal dependencies. Its root directory is the repository root, and most of its source code is located in src. Its 'global' code is located there, and subdirectories represent modules following a conventional structure. This section mostly focuses on how the server code is organised.
The PWA is built in React with TypeScript and uses Vite for development and build tooling. Its root directory is web and most of its source code is located in the corresponding src directory. Unlike the server app, this does not use a strong modular structure owing to its comparative simplicity. This may change in the future with expansion of scope.
The server app builds a 'context object' in its main function and then passes this down (usually by reference) to other code locations while constructing the app. This supports and encourages a functional, often stateless approach to adding new code. Where there is state, this is usually in the form of currying, where a new function is built using context objects or data.
The full context type is summarised in src/types.ts.
The server includes a simple logger which can be configured to provide more or less detail, depending on your needs. For development you may want to use debug or even trace level, whereas in production you most likely only need to see warn and error messages.
The logger context is put together in src/log.ts.
The server connects to MongoDB using the standard MongoClient. Data management proper typically goes through models that provide database initialization, common procedures, and where appropriate direct access to MongoDB collections.
Each module includes a model.ts file encapsulating relevant database functionality. For example, src/account/model.ts includes functions for creating and updating accounts with expanded support for password changes, amongst others.
The database context is created in src/db.ts.
Each module includes an api.ts file which exports functions reflecting REST procedures. For example, src/account/api.ts describes APIs for managing and accessing accounts.
The headless (RESTful) API is put together in src/http.ts.
On the client side, the best reference for the headless server API is in the API client library. This is maintained as part of the PWA in web/src/api.
Authentication uses JSON Web Tokens (JWT). This is expressed within the server as an authentication context in src/auth.ts, which is mainly used by API middleware and some account APIs.
Refer to the API client library for client-side usage. In terms of the PWA proper, authentication is managed via the useSession hook (using SessionContext) and verified by the Authenticated component.