anytype-ts/AGENTS.md

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
2. State Management with MobX
3. Electron Integration
4. Inter-Process Communication (IPC)
5. Routing
6. Internationalization (i18n)
7. Testing
8. Build and Packaging
9. Development Workflow
10. 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.

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.

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.

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:

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:

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:

window.api.send('channel-name', data);

• Main Process:

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.

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:

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:

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:

test('adds two numbers', () => {
  expect(add(2, 3)).toBe(5);
});

• Component Testing:

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:

npm run dev

• Production Build:

npm run build

• Packaging:

npm run dist

---

Development Workflow

1. Install Dependencies:

npm install

2. Start Development Server:

npm run dev

3. Start Electron:

npm run electron

4. Run Tests:

npm test

---

References

• Electron Documentation
• React Documentation
• MobX Documentation
• TypeScript Documentation
• React Router Documentation
• react-intl Documentation