# Project Mycelium

## Installation

### Prerequisites

- Rust and Cargo (latest stable version)
- Git

### Setup

1. Clone the repository:
   ```bash
   git clone https://git.ourworld.tf/tfgrid_research/projectmycelium
   cd projectmycelium
   ```

2. Build the project:
   ```bash
   cargo build
   ```

3. Run the application:
   ```bash
   cargo run
   ```

To run with a different port:

```
cargo run -- --port 9998
```

4. Open your browser and navigate to `http://localhost:9999`

## Architecture

Project Mycelium is a Rust web app built on Actix Web.

- **Backend (Rust/Actix Web):**
  - Routes: `src/routes/mod.rs`
  - Controllers: `src/controllers/`
  - Middleware: `src/middleware/`
  - Config: `src/config/`
  - Library crate: `src/lib.rs`; Binary: `src/main.rs`
- **Views and Static Assets:**
  - Templates (Tera): `src/views/`
  - Frontend JS: `src/static/js/` (CSP-compliant; no inline JS)
- **API Contract:**
  - Responses follow a `ResponseBuilder` JSON envelope. Frontend unwraps with:
    ```js
    const result = await response.json();
    const data = result.data || result;
    ```
  - Display rules: render "No limit" for null/undefined numeric limits; prefer server-formatted amounts.

## Marketplace Overview

- **Roles & Areas**
  - End user, Farmer, App Provider, Service Provider dashboards: `/dashboard/{user|farmer|app-provider|service-provider}` (see `DashboardController` in `src/controllers/dashboard.rs`).
  - Public catalogue: `/marketplace`, `/products`, `/products/{id}`, `/cart`, `/checkout`.
- **Core Concepts**
  - Products (apps, services, compute). Orders and cart lifecycle.
  - Slices (compute resources) on the ThreeFold Grid, publicly listed at `/marketplace/compute`.
  - Credits wallet for balance, transactions, quick top-up, and auto top-up.
- **Primary Flows**
  - Browse products: `/products`, details at `/products/{id}`; APIs under `/api/products*`.
  - Cart & checkout: `/cart`, `/checkout`; APIs under `/api/cart*` and `/api/orders*`.
  - Slice rental: forms at `/marketplace/slice/rent*`; APIs include `/api/products/{id}/rent` and `/api/marketplace/rent-slice`.
  - Wallet & credits: dashboard page `/dashboard/wallet`; APIs under `/api/wallet/*` (balance, transactions, instant purchase, quick top-up, auto top-up).
  - Settings & SSH keys: `/dashboard/settings`; APIs under `/api/dashboard/settings/*` and `/api/dashboard/ssh-keys*`.

## Security & CSP

- **Security headers** (via `SecurityHeaders` in `src/middleware/mod.rs`, enabled in `src/main.rs`):
  - `X-Content-Type-Options: nosniff`
  - `X-Frame-Options: DENY`
  - `X-XSS-Protection: 1; mode=block`
- **CSP practice**:
  - No inline JavaScript in templates; all JS under `src/static/js/`.
  - Templates (Tera) should hydrate data via JSON blocks, keeping CSP-friendly structure.
  - Note: A `Content-Security-Policy` response header is not set yet. Recommended policy (production):
    ```
    Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'
    ```
    Adjust as needed for external assets or APIs.

### Authentication & Sessions

- **Auth flows** (`src/routes/mod.rs`):
  - Gitea OAuth when `GITEA_CLIENT_ID` is set (see `src/config/oauth.rs`).
  - Username/password login otherwise (`src/controllers/auth.rs`).
- **Password hashing**: `bcrypt` for stored password hashes.
- **Sessions** (`actix-session`):
  - Cookie store with `HttpOnly` and `SameSite=Lax`, TTL 2h, name `project_mycelium_session`.
  - `cookie_secure=false` in dev; enable `true` behind HTTPS in production.
- **JWT** (`auth_token` cookie):
  - Set as `HttpOnly`; `secure=false` in dev. Enable `secure=true` in production.
  - Dashboard and protected scopes are wrapped by `JwtAuth` middleware.

## Repository Layout

- `docs/dev/` — Design, guides, and methodologies
  - Roadmap and UX contracts: `docs/dev/design/projectmycelium-roadmap.md`
- `docs/ops/` — Ops notes and runbooks
- `config/zinit/` — Service definitions (dev/prod)
- `scripts/` — Utilities and deployment helpers
- `src/` — Application source (routes, controllers, views, static assets)
- `tests/frontend_ux/` — UX test suite (feature-gated)
- `user_data/` — Test fixtures and persistent data used by UX tests

## Documentation

Key design and UX contract documentation lives in:

- `docs/dev/design/projectmycelium-roadmap.md`
  - Canonical UX contracts (e.g., SSH Keys, Settings, Auto Top-Up)
  - Proven debugging methodology and marketplace-wide audit plan

## Testing

UX tests are written in Rust using WebDriver clients (`thirtyfour`, `fantoccini`) and run under the `ux_testing` feature flag.

- **Run all UX tests:**
  ```bash
  cargo test --features ux_testing -- --nocapture
  ```
- **Individual suites** (from `Cargo.toml`):
  - `public_access_ux`, `authentication_ux`, `purchase_cart_ux`, `credits_wallet_ux`
  - `marketplace_categories_ux`, `provider_dashboards_ux`, `settings_management_ux`, `ssh_key_frontend_ux`
- **Requirements:** Ensure a compatible WebDriver (e.g., ChromeDriver/GeckoDriver) is available on PATH.
- **Pattern:** Tests follow a per-step runner with persistent fixtures under `user_data/` for deterministic results.

## Develop

> see https://git.ourworld.tf/herocode/rweb_starterkit is the web starter kit

## Usage

### Basic Usage

Once the application is running, you can access it through your web browser at `http://localhost:9999`. The default configuration provides:

- Home page at `/`
- About page at `/about`
- Contact page at `/contact`
- Login page at `/login`
- Registration page at `/register`

### Configuration

> see https://git.ourworld.tf/herocode/rweb_starterkit is the web starter kit