From 25ca3b1a00a45bbaa2b6791260fe9384173cb71a Mon Sep 17 00:00:00 2001
From: Andrew Simachev <andrew.simachev@gmail.com>
Date: Mon, 2 Jun 2025 10:37:31 +0200
Subject: [PATCH] AGENTS.md

---
 AGENTS.md | 305 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 305 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..72ee4d4c03
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,305 @@
+
+# agents.md
+
+## Overview
+
+This document outlines the architecture and implementation details of the Electron application built with React, TypeScript, and MobX. It covers the project's structure, state management, inter-process communication, and other essential aspects to facilitate understanding and contribution.
+
+## Table of Contents
+
+1. [Project Structure](#project-structure)
+2. [State Management with MobX](#state-management-with-mobx)
+3. [Electron Integration](#electron-integration)
+4. [Inter-Process Communication (IPC)](#inter-process-communication-ipc)
+5. [Routing](#routing)
+6. [Internationalization (i18n)](#internationalization-i18n)
+7. [Testing](#testing)
+8. [Build and Packaging](#build-and-packaging)
+9. [Development Workflow](#development-workflow)
+10. [References](#references)
+
+---
+
+## Project Structure
+
+The project follows a modular structure to separate concerns and enhance maintainability:
+
+```
+project-root/
+├── public/
+├── src/
+│   ├── main/               # Electron main process
+│   │   └── main.ts
+│   ├── renderer/           # React application
+│   │   ├── components/     # Reusable UI components
+│   │   ├── pages/          # Page components
+│   │   ├── stores/         # MobX stores
+│   │   ├── utils/          # Utility functions
+│   │   ├── App.tsx         # Root component
+│   │   └── index.tsx       # Entry point
+├── package.json
+├── tsconfig.json
+├── webpack.config.js
+└── ...
+```
+
+---
+
+## State Management with MobX
+
+MobX is utilized for state management, providing a simple and scalable solution.
+
+- **Store Initialization**: Each domain has its own store class, decorated with `makeAutoObservable` to enable reactivity.
+
+```typescript
+import { makeAutoObservable } from 'mobx';
+
+class TodoStore {
+  todos = [];
+
+  constructor() {
+    makeAutoObservable(this);
+  }
+
+  addTodo(todo) {
+    this.todos.push(todo);
+  }
+}
+
+export const todoStore = new TodoStore();
+```
+
+- **Context Provider**: Stores are provided to React components via Context API.
+
+```typescript
+import React from 'react';
+import { todoStore } from './stores/TodoStore';
+
+export const StoreContext = React.createContext({
+  todoStore,
+});
+```
+
+- **Usage in Components**: Components consume stores using the `useContext` hook and are wrapped with `observer`.
+
+```typescript
+import React, { useContext } from 'react';
+import { observer } from 'mobx-react-lite';
+import { StoreContext } from '../StoreContext';
+
+const TodoList = observer(() => {
+  const { todoStore } = useContext(StoreContext);
+
+  return (
+    <ul>
+      {todoStore.todos.map(todo => (
+        <li key={todo.id}>{todo.title}</li>
+      ))}
+    </ul>
+  );
+});
+
+export default TodoList;
+```
+
+---
+
+## Electron Integration
+
+Electron enables the creation of cross-platform desktop applications using web technologies.
+
+- **Main Process**:
+
+```typescript
+import { app, BrowserWindow } from 'electron';
+
+function createWindow() {
+  const win = new BrowserWindow({
+    width: 800,
+    height: 600,
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.js'),
+    },
+  });
+
+  win.loadURL('http://localhost:3000');
+}
+
+app.whenReady().then(createWindow);
+```
+
+- **Preload Script**:
+
+```typescript
+import { contextBridge, ipcRenderer } from 'electron';
+
+contextBridge.exposeInMainWorld('api', {
+  send: (channel, data) => ipcRenderer.send(channel, data),
+  receive: (channel, func) => ipcRenderer.on(channel, (event, ...args) => func(...args)),
+});
+```
+
+---
+
+## Inter-Process Communication (IPC)
+
+IPC facilitates communication between the main and renderer processes.
+
+- **Renderer Process**:
+
+```typescript
+window.api.send('channel-name', data);
+```
+
+- **Main Process**:
+
+```typescript
+ipcMain.on('channel-name', (event, data) => {
+  event.reply('channel-name-response', responseData);
+});
+```
+
+---
+
+## Routing
+
+React Router is employed for client-side routing within the renderer process.
+
+```typescript
+import { BrowserRouter as Router, Route, Switch } from 'react-router-dom';
+
+const App = () => (
+  <Router>
+    <Switch>
+      <Route path="/" exact component={HomePage} />
+      <Route path="/about" component={AboutPage} />
+    </Switch>
+  </Router>
+);
+```
+
+---
+
+## Internationalization (i18n)
+
+The application supports multiple languages using `react-intl`.
+
+- **Provider Setup**:
+
+```typescript
+import { IntlProvider } from 'react-intl';
+import messages_en from './translations/en.json';
+import messages_de from './translations/de.json';
+
+const messages = {
+  en: messages_en,
+  de: messages_de,
+};
+
+const language = navigator.language.split(/[-_]/)[0];
+
+const App = () => (
+  <IntlProvider locale={language} messages={messages[language]}>
+    {/* Application components */}
+  </IntlProvider>
+);
+```
+
+- **Usage in Components**:
+
+```typescript
+import { FormattedMessage } from 'react-intl';
+
+const Greeting = () => (
+  <p>
+    <FormattedMessage id="app.greeting" defaultMessage="Hello, World!" />
+  </p>
+);
+```
+
+---
+
+## Testing
+
+Testing ensures the reliability of the application.
+
+- **Unit Testing**:
+
+```typescript
+test('adds two numbers', () => {
+  expect(add(2, 3)).toBe(5);
+});
+```
+
+- **Component Testing**:
+
+```typescript
+import { render, screen } from '@testing-library/react';
+import TodoList from './TodoList';
+
+test('renders todo items', () => {
+  render(<TodoList />);
+  expect(screen.getByText(/Sample Todo/i)).toBeInTheDocument();
+});
+```
+
+---
+
+## Build and Packaging
+
+- **Development Build**:
+
+```bash
+npm run dev
+```
+
+- **Production Build**:
+
+```bash
+npm run build
+```
+
+- **Packaging**:
+
+```bash
+npm run dist
+```
+
+---
+
+## Development Workflow
+
+1. **Install Dependencies**:
+
+```bash
+npm install
+```
+
+2. **Start Development Server**:
+
+```bash
+npm run dev
+```
+
+3. **Start Electron**:
+
+```bash
+npm run electron
+```
+
+4. **Run Tests**:
+
+```bash
+npm test
+```
+
+---
+
+## References
+
+- [Electron Documentation](https://www.electronjs.org/docs)
+- [React Documentation](https://reactjs.org/docs/getting-started.html)
+- [MobX Documentation](https://mobx.js.org/README.html)
+- [TypeScript Documentation](https://www.typescriptlang.org/docs/)
+- [React Router Documentation](https://reactrouter.com/)
+- [react-intl Documentation](https://formatjs.io/docs/react-intl/)