# Merchant Operator Web

Merchant Operator App is a browser-only React SPA that lets local businesses create, edit, and audit their own merchant records on Local—a community-commerce network running on the peer-to-peer FogBox stack. Its mission is to decentralize ownership of commercial data and return technological control to merchants and their customers. Data is written locally first, then synchronised through FogBox nodes—no central server—ensuring autonomy and resilience. Open, well-documented APIs let any citizen-developer extend, fork, or integrate the codebase without gatekeepers.

## Architecture

This project follows a Flux-style architecture using Effector for state management. The architecture is organized around domains, with each domain containing its model (events, stores, effects), view-model (React hooks), and UI components.

For more details, see the [Architecture Documentation](./docs/architecture.md).

## Project Structure

The project follows a domain-driven structure for better maintainability and scalability:

```
merchant-operator-web/
├── src/
│   ├── app/              # Application entry point and configuration
│   │   ├── root.tsx     # Root component
│   │   └── routes.tsx   # Route definitions
│   ├── domains/          # Feature domains
│   │   └── <feature>/   # e.g., products, auth, orders
│   │       ├── model.ts # Effector events, stores, effects
│   │       ├── view-model.ts # React hooks
│   │       └── ui/      # React components
│   ├── shared/          # Shared code
│   │   ├── lib/        # Utilities, helpers, adapters
│   │   └── ui/        # Reusable UI components
│   ├── assets/          # Static assets (images, fonts)
│   ├── styles/          # Global styles
│   └── types/           # TypeScript types
├── public/              # Static files
├── config/              # Build/env configuration
└── docs/                # Documentation
```

## Path Aliases

The project uses path aliases for cleaner imports:

- `@` - Points to the `src` directory
- `@app` - Points to the `src/app` directory
- `@domains` - Points to the `src/domains` directory
- `@shared` - Points to the `src/shared` directory
- `@shared/ui` - Points to the `src/shared/ui` directory
- `@shared/lib` - Points to the `src/shared/lib` directory
- `@assets` - Points to the `src/assets` directory
- `@styles` - Points to the `src/styles` directory
- `@types` - Points to the `src/types` directory

## Development

### Prerequisites

- Node.js (v18+)
- npm or yarn

### Installation

```bash
npm install
```

### Running the Development Server

```bash
npm run dev
```

### Building for Production

```bash
npm run build
```

### Preview Production Build

```bash
npm run preview
```

## Configuration

The application uses runtime environment variables for configuration, which are injected into the application through `window.appConfig`.

For detailed configuration options, see the [Configuration Documentation](./docs/configuration.md).

## Documentation

For more detailed documentation, see the [docs](./docs) directory:

- [Architecture](./docs/architecture.md) - Overview of our Flux-style architecture with Effector
- [Project Structure](./docs/project-structure.md) - Detailed explanation of our project structure
- [Configuration](./docs/configuration.md) - Detailed configuration options and environment variables
- [Effector Guide](./docs/effector-guide.md) - Comprehensive guide on how to use Effector
- [TypeScript Conventions](./docs/typescript-conventions.md) - TypeScript conventions for the project