Added README as entry for dev documentation and updated all documentation pages.

Author: Nils-Kolvenbach

documentation/README.md

@@ -0,0 +1,43 @@
+# Developer Documentation
+
+Welcome to the elek.io Client developer documentation. This guide will help you understand the codebase architecture and development patterns.
+
+> [!NOTE]
+> If your main interest is using Projects content inside your own applications, you can skip to the [Consuming Content Locally](./consuming-content-locally.md) section.
+
+## Prerequisites
+
+- Familiarity with TypeScript and React
+- Basic understanding of Electron architecture
+- Knowledge of React Hook Form and TanStack Query (helpful but not required)
+- Understanding of Git and version control concepts
+
+## Getting Started
+
+**Start with [Overview](./overview.md)** to understand the application architecture, security model, and how the different processes communicate.
+
+Then proceed to the specific topics based on your interests or contribution goals:
+
+- **[Loading and Updating Data](./renderer/loading-and-updating-data.md)** - TanStack Query patterns for data fetching and mutations
+- **[Dynamic Form Generation](./renderer/dynamic-form-field-generation.md)** - How user-defined forms work with field definitions
+
+## Contributing
+
+When updating these docs:
+
+- Keep code examples up-to-date with actual implementation
+- Include file references with line numbers where relevant
+- Add practical examples for complex concepts
+- Update the "Last Updated" date at the bottom of each document
+
+## Additional Resources
+
+- [Electron Documentation](https://www.electronjs.org/docs/latest)
+- [TanStack Query Documentation](https://tanstack.com/query/latest)
+- [React Hook Form Documentation](https://react-hook-form.com/get-started)
+- [shadcn/ui Documentation](https://ui.shadcn.com/docs)
+- [@elek-io/core Repository](https://github.com/elek-io/core)
+
+---
+
+**Last Updated:** 2025-11-18

documentation/consuming-content-locally.md

@@ -1,94 +1,212 @@
-# Consuming content locally
+# Consuming Content Locally
 
-Consuming created content is essential to actually benefit from a CMS. elek.io Client and Core therefore provide multiple ways of doing so.
+## Overview
 
-**Use Cases**:
+Once you've created content in elek.io, you probably want to consume it in your applications. elek.io Client and Core provide multiple ways to access your Project data from external applications.
 
-- Static site generators (Next.js, Gatsby, Hugo)
-- Custom build tools
-- Really anything you can think of
+**Common Use Cases**:
 
-## Export Project data to JSON file
+- **Static Site Generators**: Fetch content for Next.js, Gatsby, Astro, Hugo, etc.
+- **Custom Build Tools**: Integrate content into your CI/CD pipeline
+- **Mobile Apps**: Access content via the local API from React Native, Flutter, etc.
+- **Desktop Applications**: Read content from other Electron or native apps
+- **Documentation Sites**: Generate docs from your elek.io content
+- **Data Analysis**: Export content for analytics or reporting tools
 
-elek.io Core can be installed globally via your package manager of choice:
+## Export Project Data to JSON Files
+
+### Installation
+
+First, install elek.io Core globally via your package manager:
 
 ```bash
 npm install -g @elek-io/core
 ```
 
-With the included CLI you can then run one of the following commands inside e.g. your websites source code directory:
+### Export Commands
+
+The built-in CLI allows you to export Project data to JSON files. Run these commands e.g. inside your website's source code directory (or any directory where you want the exported data). Alternatively integrate them into your build scripts or CI/CD pipelines to ensure your application always has the latest content:
 
 ```bash
 # Export all Projects content to .elek.io/projects.json
 elek export
 
-# Export one Project to .elek.io/projects.json
-elek export ./.elek.io [projectId]
+# Export one Project by ID to .elek.io/projects.json
+elek export ./.elek.io 467e57ea-e04a-44a7-b34b-684ed3ba6f49
 
 # Export one Project to .elek.io/project-${id}.json
-elek export ./.elek.io [projectId]
+elek export ./.elek.io 467e57ea-e04a-44a7-b34b-684ed3ba6f49
 
 # Export multiple Projects into separate .elek.io/project-${id}.json files
-elek export ./.elek.io [projectId1,projectId2] --separate
+elek export ./.elek.io 467e57ea-e04a-44a7-b34b-684ed3ba6f49,bcffed17-4946-4336-b420-3974d9c94a43 --separate
 ```
 
-Add the `-w` or `--watch` option to any of these commands to automatically re-export whenever a Project changes.
+> [!NOTE]
+> Replace `467e57ea-e04a-44a7-b34b-684ed3ba6f49` with your actual Project ID. You can find Project IDs in the elek.io Client UI or in your Project's `.elek.io` directory.
+
+### Watch Mode
 
-Then use the content inside these JSON file(s) to populate your website or application:
+Add the `-w` or `--watch` flag to automatically re-export whenever a Project changes:
+
+```bash
+elek export ./.elek.io 467e57ea-e04a-44a7-b34b-684ed3ba6f49 --watch
+```
+
+This is particularly useful during development when you're actively updating content.
+
+### Using Exported JSON
+
+Once exported, you can import and use the JSON data in your application:
 
 ```typescript
 import * as projects from './.elek.io/projects.json' with { type: 'json' };
 
-const entries = projects['...'].collections['...'].entries;
+// Access a specific Project's Collections
+const myProject = projects['467e57ea-e04a-44a7-b34b-684ed3ba6f49'];
+const blogPosts = myProject.collections['blog-posts'].entries;
 
-// Use the Entries
+// Use the Entries in your app
+blogPosts.forEach((post) => {
+  console.log(post.title, post.content);
+});
 ```
 
 ## Local API
 
-Enable the local API in your User Profile of elek.io Client → "Enable Local API Server". Then you can visit `http://localhost:31310/` (or your specified port) to view a rendered OpenAPI documentation and execute queries.
+elek.io Core also provides a local REST API server that runs on your machine, allowing applications to query your elek.io Projects for content.
+
+### Enabling the Local API
+
+**Via elek.io Client**
+
+1. Open elek.io Client
+2. Navigate to **User Profile** (top-right menu)
+3. Scroll to the **Local API** section
+4. Toggle **"Enable Local API Server"**
+5. Optionally change the port (default: `31310`)
+6. Click **Save**
+
+**Via elek.io Core**
+
+You can also start the local API server directly using elek.io Core CLI:
+
+```bash
+elek api:start 31310
+```
+
+Or programmatically in your Node.js application:
+
+```typescript
+import ElekIoCore from '@elek-io/core';
+
+const core = new ElekIoCore();
+core.api.start(31310);
+```
+
+Once enabled, you can visit `http://localhost:31310/` (or your specified port) to view the OpenAPI documentation and execute test queries.
+
+> [!WARNING]
+> Make sure the port you choose is not already in use by another application. If the API fails to start, try a different port.
 
-### Generate TS/JS API Client
+### Generate TypeScript/JavaScript API Client
 
-Of course you could write an API Client yourself but for TypeScript / JavaScript applications we provide a generated API Client with validation.
+While you can write an API client manually, elek.io provides a code generator that creates a type-safe client with built-in validation for TypeScript and JavaScript applications.
 
-Install elek.io Core globally via your package manager of choice:
+#### Generate the Client
+
+If you haven't already, install elek.io Core globally:
 
 ```bash
 npm install -g @elek-io/core
 ```
 
-Then use the CLI to generate a TS or JS API Client with one of the following commands:
+Then generate the API client:
 
 ```bash
-# Generate TS API Client with default options in ./.elek.io/client.ts
+# Generate TypeScript API Client with default options in ./.elek.io/client.ts
 elek generate:client
 
-# Generate JS API Client with ESM and target ES2020 in ./.elek.io/client.ts
+# Generate JavaScript API Client with ESM and target ES2020
 elek generate:client ./.elek.io js esm es2020
 ```
 
-Then import and use the generated API Client like:
+#### Using the Generated Client
+
+Import and use the generated API client in your application:
 
 ```typescript
 import { apiClient } from './.elek.io/client.js';
 
 const client = apiClient({
   baseUrl: 'http://localhost:31310',
-  apiKey: 'abc123', // Not used for now
+  apiKey: 'abc123', // Not currently used, reserved for future authentication
 });
 
-const entries =
-  await client.content.v1.projects['...'].collections['...'].entries.list();
+// Fetch all Entries from a specific Collection
+const blogPosts =
+  await client.content.v1.projects[
+    '467e57ea-e04a-44a7-b34b-684ed3ba6f49'
+  ].collections['blog-posts'].entries.list();
+
+// Access individual Entries
+blogPosts.forEach((post) => {
+  console.log(post.title, post.publishedAt);
+});
 ```
 
-### Generate API Client for other languages
+### Generate API Client for Other Languages
 
-For languages other than TS/JS you can either write an API Client yourself, or use an OpenAPI generator like:
+For languages other than TypeScript/JavaScript, you can use any OpenAPI-compatible code generator. The local API exposes its full schema at `/openapi.json`.
+
+#### Example: Generate a Java Client
 
 ```bash
 npx openapi-generator-cli generate \
   -i http://localhost:31310/openapi.json \
   -g java \
   -o ./.elek.io/client
 ```
+
+#### Example: Generate a Python Client
+
+```bash
+npx openapi-generator-cli generate \
+  -i http://localhost:31310/openapi.json \
+  -g python \
+  -o ./.elek.io/client
+```
+
+> [!NOTE]
+> Make sure the local API is running before generating the client, as the generator needs to fetch the OpenAPI schema.
+
+For more generators and options, see the [OpenAPI Generator documentation](https://openapi-generator.tech/docs/generators).
+
+## Troubleshooting
+
+### Port Already in Use
+
+If you see an error that the port is already in use:
+
+1. Check which application is using the port: `lsof -i :31310` (macOS/Linux) or `netstat -ano | findstr :31310` (Windows)
+2. Either stop that application or choose a different port
+
+### API Not Starting
+
+If the local API fails to start:
+
+1. Check the elek.io Client logs for error messages
+2. Ensure you have the latest version of elek.io Client and Core
+3. Try restarting elek.io Client
+4. Verify no firewall is blocking the port
+
+### Generated Client Not Working
+
+If the generated API client has type errors or runtime issues:
+
+1. Regenerate the client with the latest schema
+2. Ensure the local API is running and accessible
+3. Check that your Project IDs and Collection IDs are correct
+
+---
+
+**Last Updated:** 2025-11-18

documentation/overview.md

@@ -1,6 +1,15 @@
 # Overview
 
-elek.io Client is built on [Electron](https://www.electronjs.org/), to create a cross-platform desktop application with web technologies (TypeScript, React). The architecture consists of three main layers: the Main Process, the Preload Script, and the Renderer Process.
+## Introduction
+
+elek.io Client is built on [Electron](https://www.electronjs.org/) to create a cross-platform desktop application with web technologies (TypeScript, React).
+
+> [!NOTE]
+> By choosing Electron, we keep the languages (everything is mainly TypeScript) used throughout our repositories to a minimum and the knowledge barrier for potential contributors low. Although applications build e.g. with [Tauri](https://tauri.app/) do have a smaller bundle size and memory footprint, adding another language (Rust) would increase complexity for contributors by alot.
+
+## Architecture
+
+Electron applications consist of three main layers: the Main Process, the Preload Script, and the Renderer Process.
 
 ```
 ┌─────────────────────────────────────────────────────────┐
@@ -24,7 +33,7 @@ elek.io Client is built on [Electron](https://www.electronjs.org/), to create a
 
 While elek.io Client provides the user interface in a desktop application, all core functionalities related to file I/O, content handling, Git operations, local read-only API hosting and CLI usage are encapsulated in the separate [@elek-io/core](https://github.com/elek-io/core) library.
 
-It is used by the Main Process, since only it has access to the filesystem and Node.js APIs - the Renderer Process is sandboxed for security reasons.
+@elek-io/core is used by the Main Process, since only it has access to the filesystem and Node.js APIs - the Renderer Process is sandboxed for security reasons.
 
 Therefore the Renderer Process communicates with the Main Process via IPC (Inter-Process Communication) to request operations via @elek-io/core.
 
@@ -61,11 +70,11 @@ contextBridge.exposeInMainWorld('ipc', {
 // Renderer process uses the IPC API (src/renderer/)
 const project = await window.ipc.core.projects.create({
   name: 'My Project',
-  description: 'A new project',
+  description: 'A new Project',
 });
 ```
 
-50+ IPC Channels are available and organized by namespace.
+35+ IPC Channels are available and organized by namespace.
 
 ### Project Structure
 
@@ -83,6 +92,7 @@ client/
 │       │   └── ui/        # UI components
 │       ├── hooks/         # React hooks
 │       ├── lib/           # Utilities
+│       ├── queries/       # Data fetching, mutations and caching
 │       ├── routes/        # File-based routing
 │       │   ├── projects/
 │       │   │   ├── $projectId/
@@ -98,9 +108,7 @@ client/
 │       │   │   └── profile.tsx
 │       │   └── __root.tsx
 │       ├── app.tsx        # App entry point
-│       ├── ipc.ts         # IPC communication
-│       ├── sentry.ts      # Error monitoring
-│       └── store.ts       # State management
+│       └── index.ts       # Error monitoring and router setup
 ├── build/                 # Build resources (icons, etc.)
 ├── documentation/         # Developer docs
 ├── electron-builder.yml   # Build configuration
@@ -111,7 +119,9 @@ client/
 
 ### Security
 
-As mentioned, elek.io Client only allows the Renderer Process to communicate with the Main Process via a controlled IPC API exposed through the Preload Script. This follows the [security best practices of Electron](https://www.electronjs.org/docs/latest/tutorial/security) and ensures that untrusted code running in the Renderer Process (e.g. third-party libraries, users content) cannot directly access Node.js APIs or the filesystem.
+Handling user content that is distributed and could potentially be malicious within an app that has access to the file system, strict security is necessary. elek.io Client follows [Electron's security best practices](https://www.electronjs.org/docs/latest/tutorial/security) to create strong isolation boundaries.
+
+The Renderer Process can only communicate with the Main Process via a controlled IPC API exposed through the Preload Script. This ensures that untrusted code running in the Renderer Process (e.g., third-party libraries or user content) cannot directly access Node.js APIs or the filesystem.
 
 #### Renderer Process Isolation
 
@@ -131,14 +141,28 @@ A Content Security Policy is enforced via a `<meta>` tag in the `src/renderer/in
 
 #### External Content Restrictions
 
-Some links to elek.io domains and loading of content are allowed in elek.io Client. To prevent abuse, the following restrictions are in place:
+Some links to elek.io domains and loading of content are allowed in elek.io Client. To prevent abuse and potential security risks, the following restrictions are in place:
 
 **URL Whitelisting**:
 
-All external requests (e.g. when a user clicks a link inside the renderer or an Asset is displayed) are checked against a whitelist. See `allowedHostnamesToLoadExternal` in [`src/main/index.ts`](/src/main/index.ts).
+All external requests (e.g., when a user clicks a link inside the renderer or an Asset is displayed) are checked against a whitelist of allowed hostnames:
 
-Links to these hostnames are opened inside the default browser, not an elek.io Client renderer.
+- `elek-io-local-file://` (custom file protocol)
+- `localhost`
+- `elek.io`
+- `api.elek.io`
+- `github.com`
+
+See `allowedHostnamesToLoadExternal` in [`src/main/index.ts:41-46`](/src/main/index.ts) for the implementation.
+
+Links to whitelisted external hostnames are opened in the default system browser, not within an elek.io Client renderer window.
 
 **Custom File Protocol**:
 
-Loading of Assets in the UI is handled via a custom file protocol `elek-io-local-file://` since the standard `file://` protocol in electron has more privileges than in a browser. This ensures path validation (must be within project or tmp folders) and prevents directory traversal.
+Loading of Assets in the UI is handled via a custom file protocol `elek-io-local-file://` since the standard `file://` protocol in Electron has more privileges than in a browser. This custom protocol implementation ensures path validation (files must be within Project or tmp folders) and prevents directory traversal attacks.
+
+See [`src/main/index.ts:267-305`](/src/main/index.ts) for the custom protocol implementation.
+
+---
+
+**Last Updated:** 2025-11-18