kashilo/README.md

# kashilo.com

A privacy-first classifieds platform with Monero payments.

## 🎯 Vision

kashilo.com lets users post classifieds and trade goods/services securely via Monero (XMR).

- **Anonymous**: No personal data required
- **Direct payments**: Peer-to-peer via Monero, no payment intermediary
- **Privacy-first**: End-to-end encrypted communication

---

## 📊 Features

| Feature | Complexity | Status |
|---------|------------|--------|
| Listings CRUD | Low | ✅ Done |
| Fiat/XMR price display | Low | ✅ Done |
| Anonymous accounts (UUID + Hash) | Medium | ✅ Done |
| PWA | Medium | ✅ Done |
| Light/Dark Mode | Low | ✅ Done |
| i18n (7 languages) | Low | ✅ Done |
| Image gallery | Low | ✅ Done |
| E2E Chat (NaCl box.before + secretbox) | High | ✅ Done |
| PoW Captcha (server-side) | Medium | ✅ Done |
| Rating & Reputation system | Medium | ✅ Done |
| Verifiable Listings | Medium | ✅ Done |
| Pseudonyms & Identicons | Low | ✅ Done |
| Invite code system (alpha) | Low | ✅ Done |
| 2FA | Medium | 🔲 Planned |

---

## 🛠️ Tech Stack

### Frontend
- **Vanilla JavaScript** (ES Modules)
- **Web Components** (Custom Elements)
- **CSS Custom Properties** (Theming)
- **PWA** (Service Worker, Manifest)

### Backend
- **Directus** (Headless CMS, self-hosted)
  - REST API
  - Auth, roles, permissions

### Services
- **Directus** backend: `api.kashilo.com` (Docker)
- **PoW Captcha + Payment Proxy**: `pow.kashilo.com` (PHP, HMAC-signed challenges, BTCPay proxy + webhook, OG meta proxy)
- **BTCPay Server**: `pay.xmr.rocks` (Monero payments, self-hosted)
- **TweetNaCl**: Self-hosted in `js/vendor/` (E2E encryption)

### Planned
- Push notifications (Web Push API)

---

## 🚀 Setup

### Prerequisites
- Modern browser with ES Module support
- Python 3 (for local server) or any HTTP server

### Installation

```bash
# Clone the repository
git clone https://gitea.pro/schmidt1024/kashilo.git
cd kashilo

# Start local server
python3 -m http.server 8080

# Or with live-reload (Node.js required)
npx live-server
```

Open http://localhost:8080

### Deployment

Production requires only these files:

```
├── index.html
├── manifest.json
├── service-worker.js
├── favicon.png
├── js/
├── css/
├── locales/
└── assets/
```

**Do not deploy:** `tests/`, `docs/`, `AGENTS.md`, `README.md`, `.git/`, `deploy.sh`

#### Build (minification)

```bash
# One-time: install dependencies
pip3 install rjsmin rcssmin

# Run build (creates dist/ with minified files)
python3 build.py
```

The build script minifies all JS and CSS files (~111 KiB savings) and copies everything to `dist/`.

#### Deploy via script

```bash
# One-time: adjust SSH user and path
./deploy.sh user@kashilo.com /home/user/web/kashilo.com/public_html

# Or set defaults in the script and simply run:
./deploy.sh
```

The script automatically runs `python3 build.py`, then `rsync` from `dist/` to the server.

**Requirements:**
- Python 3 + `rjsmin` + `rcssmin` (for build)
- SSH key authentication to server
- `rsync` installed locally and on the server

### Running tests

```bash
# Start server
python3 -m http.server 8080

# Open in browser
# http://localhost:8080/tests/
```

Tests run in the browser using a minimal test runner without external dependencies.

### Project structure

```
kashilo/
├── index.html              # Entry point
├── manifest.json           # PWA Manifest
├── service-worker.js       # Offline support
├── css/
│   ├── fonts.css           # Web Fonts (Inter, Space Grotesk)
│   ├── variables.css       # Theming (Light/Dark)
│   ├── base.css            # Reset, base styles
│   └── components.css      # UI components
├── js/
│   ├── app.js              # App initialization
│   ├── router.js           # Hash-based routing
│   ├── i18n.js             # Translation system
│   ├── services/
│   │   ├── directus.js     # Directus API client
│   │   ├── auth.js         # UUID auth (SHA-256 hash)
│   │   ├── listings.js     # Listings service
│   │   ├── categories.js   # Categories service
│   │   ├── locations.js    # Locations service
│   │   ├── conversations.js# Zero-knowledge chat
│   │   ├── crypto.js       # NaCl encryption (box.before + secretbox)
│   │   ├── currency.js     # XMR/fiat conversion (Kraken + CoinGecko)
│   │   ├── pow-captcha.js  # PoW captcha (server-first, local fallback)
│   │   ├── btcpay.js       # BTCPay Server integration
│   │   ├── favorites.js    # Favorites (localStorage + Directus sync)
│   │   ├── notifications.js# Notifications (polling, badge)
│   │   ├── reputation.js   # Reputation (deals, ratings, levels)
│   │   ├── verification.js # Verifiable listings (proof of possession)
│   │   └── identity.js     # Pseudonyms & identicon avatars
│   ├── vendor/
│   │   ├── nacl-fast.min.js    # TweetNaCl (self-hosted)
│   │   ├── nacl-util.min.js    # TweetNaCl Utils
│   │   └── cropper.min.js      # Image Cropper
│   └── components/
│       ├── app-shell.js    # Layout container
│       ├── app-header.js   # Header with navigation
│       ├── app-footer.js   # Footer
│       ├── auth-modal.js   # Login/Register modal
│       ├── chat-widget.js  # E2E chat widget
│       └── pages/          # Page components
├── locales/
│   ├── de.json             # Deutsch
│   ├── en.json             # English
│   ├── fr.json             # Français
│   ├── it.json             # Italiano
│   ├── es.json             # Español
│   ├── pt.json             # Português (BR)
│   └── ru.json             # Русский
├── tests/
│   ├── index.html          # Test runner UI
│   ├── test-runner.js      # Test framework
│   └── *.test.js           # Unit tests
└── assets/
    └── fonts/              # Self-hosted fonts
```

---

## 📋 Roadmap

### Phase 1: Frontend ✅
- [x] Project structure, routing, i18n (7 languages)
- [x] Light/Dark mode, PWA shell
- [x] Home page with search, categories, listings grid
- [x] Listing detail page with image gallery
- [x] Create/edit listing form
- [x] Skeleton loading, error boundary, offline indicator

### Phase 2: Backend integration ✅
- [x] Directus setup (`api.kashilo.com`)
- [x] Listings, categories, locations collections
- [x] Anonymous auth (UUID + SHA-256 hash)
- [x] Image upload, favorites, my listings, messages, settings pages

### Phase 3: Communication & Security ✅
- [x] E2E encrypted chat (NaCl box.before + secretbox)
- [x] Favorites with Directus sync (union merge on login)
- [x] PoW captcha (server-side via pow.kashilo.com)
- [x] TweetNaCl self-hosted (no CDN)
- [x] In-app notifications (polling, badge)
- [x] Open Graph & X Card meta tags

### Phase 4: Payments ✅
- [x] XMR rate API (Kraken primary, CoinGecko fallback)
- [x] Fiat ↔ XMR conversion (dual price display)
- [x] BTCPay Server integration (self-hosted)
- [x] Listing fee: $1 via Monero
- [x] Webhook for auto-publish after blockchain confirmation
- [x] Expired listings (Directus flow, status badges)

### Phase 5: Trust & Safety ✅
- [x] Rating & reputation system (deals, levels, badges)
- [x] Verifiable listings (proof of possession)
- [x] Pseudonyms & identicon avatars
- [x] Terms of service, privacy policy, legal notice (7 languages)
- [ ] 2FA
- [ ] Reporting/moderation
- [ ] Push notifications (Web Push API)

---

## 🎨 Design

### Typography
- **Headlines**: Space Grotesk (Medium, Bold)
- **Body**: Inter (Regular, Medium, SemiBold, Bold)
- Self-hosted fonts (SIL Open Font License)

### Color palette
- **Warm Teal Theme**
- **Light Mode**: BG #FAFAF9, Text #1C1917, Accent #0D9488
- **Dark Mode**: BG #171717, Text #F5F5F4, Accent #2DD4BF

### Mobile-first
- Responsive grid (2 columns mobile, 5 columns desktop)
- Touch-optimized buttons
- Icon-only buttons on small screens

---

## 🤝 Contributing

1. Create a feature branch
2. Commit your changes
3. Open a pull request

### Code conventions
- ES Modules
- Web Components for UI
- CSS Custom Properties for theming
- Translation keys for all user-facing text
- No semicolons in JavaScript (except for-loops, CSS)
- English comments in code

---

## 📄 License

This project is licensed under the [GNU Affero General Public License v3.0 (AGPL-3.0)](LICENSE).

Source code is freely available. Forks and modifications must also be published under AGPL-3.0.

**kashilo** is a registered trademark. The name and logo may not be used for derivative projects without permission.

---

## 📞 Contact

- **Issues:** [gitea.pro/schmidt1024/kashilo/issues](https://gitea.pro/schmidt1024/kashilo/issues)
- **Website:** [kashilo.com](https://kashilo.com)