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`) |

## Häufige Befehle

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

# Oder mit Live-Reload
npx live-server

# 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](https://www.conventionalcommits.org/): `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, Preis-Formatierung)
│   ├── categories.js   # Kategorien Service (Baum, Übersetzungen)
│   ├── locations.js    # Standorte Service (Geo-Suche)
│   ├── conversations.js # Zero-Knowledge Chat (E2E verschlüsselt)
│   ├── chat.js         # LocalStorage Chat (Legacy/Mock)
│   ├── crypto.js       # NaCl Encryption
│   ├── currency.js     # XMR/Fiat Umrechnung
│   └── pow-captcha.js  # Proof-of-Work Captcha (Challenge/Verify)
└── 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

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)

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 (`page-my-listings.js`, `page-messages.js`, `page-favorites.js`, `page-settings.js`)
2. ~~Suchseite mit Filtern~~ ✅ Merged in `page-home.js`
3. ~~Listings bearbeiten~~ ✅ Edit-Modus via `#/edit/:id`
4. Payment-Integration mit BTCpay Server (https://pay.xmr.rocks/)
5. Reputation-System (5/15/50 Deals Stufen)
6. 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