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

# Lokaler Entwicklungsserver
python3 -m http.server 8080

# Oder mit Live-Reload
npx live-server

# 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: 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 (per Default wenn sicher)
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