kashilo/AGENTS.md

# AGENTS.md - AI Assistant Context

Dieses Dokument hilft AI-Assistenten (Amp, Copilot, etc.) das Projekt zu verstehen.

## Projekt-Überblick

**dgray.io** ist eine Kleinanzeigen-PWA mit Monero-Bezahlung.

- **Status**: Active Development (Frontend + Directus Backend)
- **Ziel**: Anonyme, dezentrale Marktplatz-Alternative

## Tech-Stack

| Layer | Technologie |
|-------|-------------|
| Frontend | Vanilla JS, Web Components, CSS Custom Properties |
| Routing | Hash-basierter Client-Side Router (`js/router.js`) |
| i18n | Custom System (`js/i18n.js`), JSON-Dateien in `/locales/` |
| Theming | CSS Variables, Dark/Light Mode |
| Backend | Directus (`api.dgray.io`) |
| Auth | UUID-basiert, anonym (`js/services/auth.js`) |
| E2E Crypto | TweetNaCl (self-hosted in `js/vendor/`), `box.before` + `secretbox` |
| PoW Captcha | PHP-Server (`pow.dgray.io`), Fallback auf lokal |

## Häufige Befehle

```bash
# Lokaler Entwicklungsserver
python3 -m http.server 8080

# Oder mit Live-Reload
npx live-server

# Build (JS/CSS minifizieren → dist/)
pip3 install rjsmin rcssmin   # einmalig
python3 build.py

# Deploy (baut automatisch, dann rsync von dist/)
./deploy.sh

# Tests ausführen (im Browser)
# Server starten, dann http://localhost:8080/tests/ öffnen

# Git Push (Token in URL)
git push origin master
```

## Commit-Konvention

Wenn der User nach **"commit text"** fragt:
- **Immer nur eine einzeilige** Commit-Message im Format: `git commit -m "..."`
- Keine mehrzeiligen Messages oder Body-Text
- Nutze [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
- Standardsprache: Englisch (außer User fragt explizit nach "de")

## Dateistruktur

```
js/
├── app.js              # Entry, lädt i18n, dann Shell
├── router.js           # Hash-Router mit :params
├── i18n.js             # t('key'), subscribe(), updateDOM()
├── services/
│   ├── directus.js     # Directus API Client (Core)
│   ├── auth.js         # UUID-basierte Authentifizierung (SHA-256 Hash)
│   ├── listings.js     # Listings Service (Filter)
│   ├── categories.js   # Kategorien Service (Baum, Übersetzungen, Cache)
│   ├── locations.js    # Standorte Service (Geo-Suche)
│   ├── conversations.js # Zero-Knowledge Chat (E2E verschlüsselt)
│   ├── crypto.js       # NaCl Encryption
│   ├── currency.js     # XMR/Fiat Umrechnung
│   ├── pow-captcha.js  # Proof-of-Work Captcha (Challenge/Verify)
│   ├── btcpay.js       # BTCPay Server Integration (Invoice, Checkout, Webhook)
│   ├── favorites.js    # Favoriten-Service (localStorage + Directus Sync)
│   └── notifications.js # Benachrichtigungen (Polling, Badge)
└── components/
    ├── app-shell.js    # Layout, registriert Routes
    ├── app-header.js   # Header (Theme-Toggle, Lang-Dropdown, Profil-Dropdown)
    ├── app-footer.js   # Footer
    ├── auth-modal.js   # Login/Register Modal (mit PoW-Captcha)
    ├── pow-captcha.js  # PoW-Captcha Web Component
    ├── chat-widget.js  # E2E Chat Widget
    └── pages/          # Seiten als Web Components

docs/
├── DIRECTUS-SETUP.md   # Directus Backend Setup
├── DIRECTUS-SCHEMA.md  # Collection-Strukturen & Permissions
├── MONETIZATION.md     # Monetarisierung & Anti-Abuse
├── pow-server/         # PHP PoW-Captcha Server (pow.dgray.io)
└── og-proxy.php        # Open Graph Meta-Tag Proxy (pow.dgray.io)

css/
├── fonts.css           # @font-face Definitionen (Inter, Space Grotesk)
├── variables.css       # CSS Custom Properties (Farben, Spacing)
├── base.css            # Reset, Container
└── components.css      # UI-Komponenten (Buttons, Cards, etc.)

assets/
├── fonts/              # Self-hosted Fonts (Inter, Space Grotesk)
└── press/              # Press Kit (Logos, OG-Image, Brand Guidelines)

tests/
├── index.html          # Test-Runner UI (im Browser öffnen)
├── test-runner.js      # Minimaler Test-Framework
├── helpers.test.js     # Unit Tests für helpers.js
├── i18n.test.js        # Unit Tests für i18n.js
└── router.test.js      # Unit Tests für router.js

locales/
├── de.json             # Deutsch (Fallback)
├── en.json
├── fr.json
├── it.json             # Italienisch
├── es.json             # Spanisch
├── pt.json             # Portugiesisch (BR)
└── ru.json             # Russisch
```

## Konventionen

### JavaScript
- **Keine Semikolons** am Zeilenende (außer in for-loops, CSS)
- **Englische Kommentare** im Code
- ES Modules mit `import/export`

### Web Components
- Custom Elements mit `class extends HTMLElement`
- Styles als `<style>` im `document.head` oder inline
- i18n: `render()` Methode, Subscribe auf Sprachwechsel
- Auth-Subscriber nur in `connectedCallback()`, nicht in `setupEventListeners()`

### CSS
- **Keine festen Farben** - immer `var(--color-*)` nutzen
- **Spacing**: `var(--space-xs|sm|md|lg|xl|2xl|3xl)`
- **Font-Size**: `var(--font-size-xs|sm|base|lg|xl|2xl|3xl)`
- **Font-Family**: `var(--font-family)` für Body, `var(--font-family-heading)` für Headlines
- **Border-Radius**: `var(--radius-sm|md|lg|xl|full)`
- **Breakpoint**: `@media (max-width: 768px)` - einziger Mobile-Breakpoint für alle Komponenten

### i18n
- Schlüssel: `section.key` (z.B. `home.title`)
- Im HTML: `data-i18n="key"` oder `${t('key')}`
- Placeholder: `data-i18n-placeholder="key"`
- Neue Texte in **allen 7 Sprachen** hinzufügen (de, en, fr, it, es, pt, ru)
- Frontend nutzt Kurzcodes (`de`), Directus Langcodes (`de-DE`) — Mapping in `i18n.js` (`LOCALE_TO_DIRECTUS`)

## Aktuelle Probleme / Hinweise

1. **SSH funktioniert nicht** mit diesem Repo auf gitea.pro - HTTPS mit Token nutzen
2. **Service Worker** kann lokale Änderungen cachen - bei Problemen Cache leeren
3. **i18n muss vor Shell laden** - siehe `app.js` (dynamischer Import)

## Nächste Schritte

1. ~~Seiten für Profil-Dropdown~~ ✅ Fertig
2. ~~Suchseite mit Filtern~~ ✅ Merged in `page-home.js`
3. ~~Listings bearbeiten~~ ✅ Edit-Modus via `#/edit/:id`
4. ~~PoW-Captcha server-seitig~~ ✅ PHP-Server auf `pow.dgray.io`
5. ~~TweetNaCl self-hosted~~ ✅ In `js/vendor/`
6. ~~Chat-Crypto fix~~ ✅ `box.before` + `secretbox`
7. ~~Payment-Integration mit BTCpay Server~~ ✅ Proxy auf `pow.dgray.io`, Frontend-Service `btcpay.js`
8. ~~Favoriten Directus Sync~~ ✅ FavoritesService mit Union-Merge bei Login
9. ~~Expired Listings~~ ✅ Directus Flow (alle 15 Min), Status-Badges auf Cards
10. Reputation-System (siehe Details unten)
11. ~~In-App Benachrichtigungen~~ ✅ NotificationsService mit Polling, Glocke-Icon mit Badge
12. Push-Benachrichtigungen (Web Push API)
13. ~~Monero MultiSig Escrow~~ ❌ Gestrichen (erfordert VASP-Lizenz + KYC, widerspricht Privacy-Konzept)
14. Tor Hidden Service (.onion URL)
15. Öffentliche Statistiken (Anzeigen, User, Deals — erst ab Schwellwert anzeigen)

### Reputation-System (Konzept)

- **Erfolgreiche Deals**: Stufensystem (5/15/50 abgeschlossene Transaktionen)
- **Account-Alter**: Vertrauensbonus für ältere Accounts
- **PoW-Difficulty**: Höherer PoW-Aufwand bei Registrierung als "Skin in the Game"
- Kein KYC — Vertrauen durch nachweisbare Aktivität
- Visuelles Badge/Level auf Profil und Listings

## Directus Berechtigungen (Public-Rolle)

| Collection | Read | Create | Update | Hinweise |
|------------|------|--------|--------|----------|
| `listings` | ✓ | ✓ | ✓ | Nur `status=published` lesen, Update nur `views` (Public) |
| `listings_files` | ✓ | ✓ | - | Junction-Table für Bilder |
| `directus_files` | ✓ | ✓ | - | Für Assets/Bilder |
| `categories` | ✓ | - | - | Nur `status=published` |
| `categories_translations` | ✓ | - | - | Für i18n |
| `locations` | ✓ | ✓ | - | User kann neue Orte anlegen |
| `languages` | ✓ | - | - | Für Sprachen-Liste |
| `conversations` | ✓ | ✓ | ✓ | Filter via `participant_hash`, Update nur `status` |
| `messages` | ✓ | ✓ | - | Filter via `conversation` ID |
| `favorites` | ✓ | ✓ | - | User-Rolle: Filter `user = $CURRENT_USER`, Delete erlaubt |
| `notifications` | ✓ | ✓ (via Flow/Webhook) | ✓ | User-Rolle: Filter `user_hash`, nur `read` updaten |

### Directus Flows

| Flow | Trigger | Aktion |
|------|---------|--------|
| Archive Expired Listings | Schedule `*/15 * * * *` | `status → archived` wenn `expires_at < NOW` |
| Notify: Listing Published | Webhook (btcpay-webhook.php) | Creates notification when listing is published after payment |
| Notify: New Message | Event Hook `items.create` on `messages` | Creates notification for message recipient |

Siehe `docs/DIRECTUS-SCHEMA.md` für vollständiges Schema.

## Farbpalette

```
Monochrome Theme - reine Graustufen

Light Mode:
- BG: #FAFAFA
- Text: #1A1A1A
- Primary: #555555
- Border: #D0D0D0

Dark Mode:
- BG: #141414
- Text: #F0F0F0
- Primary: #AAAAAA
- Border: #3A3A3A
```

## Ansprechpartner

- Repo: https://gitea.pro/schmidt1024/dgray