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 (en)" oder "commit text (de)" fragt:

• Erstelle eine einzeilige Commit-Message im Format: git commit -m "..."
• Nutze Conventional Commits: feat:, fix:, docs:, refactor:, chore:
• Sprache entsprechend der Anfrage (en/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, Polling)
└── 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)

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)

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

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 3 Sprachen hinzufügen

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. Reputation-System (5/15/50 Deals Stufen)
9. Push-Benachrichtigungen für neue Nachrichten

Directus Berechtigungen (Public-Rolle)

Collection	Read	Create	Update	Hinweise
listings	✓	✓	-	Nur status=published lesen
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

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