# Directory architecture for AI-generated content with IPFS and wallet-based auth

Below is an organized structure your current architecture with decentralized content storage (IPFS/Filecoin) and serverless authentication via user wallets. It keeps your static app clean, separates blockchain and storage concerns, and preserves data contracts.

---

## Proposed directory structure

```text
RewardApp/
├── index.html
├── login.html
├── register.html
├── README.md
├── config.json                     # مسیرهای IPFS/گیت‌وی، شبکه بلاکچین، آدرس کانترکت‌ها، گزینه‌های امنیت
├── error_log.txt                   # گزارش خطاهای کلاینت و ثبت رخدادها
├── css/
│   ├── style.css
│   ├── auth.css
│   └── responsive.css
├── js/
│   ├── app.js
│   ├── auth/
│   │   ├── authentication.js       # اتصال ولت، مدیریت امضا/چالش، بازیابی آدرس کاربر
│   │   ├── authorization.js        # قواعد سطح دسترسی بر اساس آدرس/نقش‌های روی‌زنجیره
│   │   └── user_management.js      # هندل وضعیت کاربر در کلاینت (بدون سرور مرکزی)
│   ├── middleware/
│   │   ├── auth_middleware.js      # محافظت از مسیرها با نیاز به اتصال ولت
│   │   └── validation_middleware.js# اعتبارسنجی ورودی‌ها و قراردادها
│   ├── logic/
│   │   ├── logic.js
│   │   ├── reward.js
│   │   ├── utils.js                # ابزارهای بارگذاری/کش/خطاپذیری
│   │   ├── blockchain_integration.js # فراخوانی قراردادها، خواندن/نوشتن روی زنجیره
│   │   ├── ipfs_integration.js     # پین/آپلود/دانلود محتوا از IPFS (از طریق گیت‌وی یا پین‌سرویس)
│   │   └── ai_integration.js       # فراخوانی مولدهای AI و آماده‌سازی خروجی برای IPFS
│   ├── ui/
│   │   ├── quiz_ui.js
│   │   ├── lesson_ui.js
│   │   ├── exercise_ui.js
│   │   └── content_creator_ui.js   # تولید محتوای جدید، ارسال به IPFS، ثبت متادیتا روی زنجیره
│   └── components/
│       ├── header.js
│       ├── modal.js
│       └── navigation.js
├── blockchain/
│   ├── contracts/                  # RewardRegistry, RewardToken, ContentRegistry (متادیتا/هش/URI)
│   ├── migrations/                 # اسکریپت‌های دیپلوی و ارتقا
│   ├── tests/                      # تست واحد/ادغام کانترکت‌ها
│   ├── config/                     # شبکه‌ها، آدرس‌ها، ABIها
│   └── wallet_integration.js       # اتصال کیف‌پول‌ها (Polkadot.js/MetaMask) و light client
├── storage/
│   ├── ipfs/
│   │   ├── pinning_client.js       # کلاینت سرویس پین (Pinata/Web3.Storage/Infura)
│   │   ├── gateway_client.js       # خواندن از گیت‌وی‌ها، fallback و کش
│   │   └── cid_index.json          # ایندکس محلی CIDها برای محتواهای اخیر/منتشرشده
│   └── cache/
│       └── content_cache.db        # کش کلاینت (IndexedDB یا فایل مجازی) برای کاهش فراخوانی شبکه
├── ai/
│   ├── generators/
│   │   ├── lesson_generator.js
│   │   ├── quiz_generator.js
│   │   ├── exercise_generator.js
│   │   └── image_generator.js
│   ├── api/
│   │   ├── ai_config.json
│   │   └── ai_client.js
│   └── validation/
│       └── schema_validator.js     # اعتبارسنجی خروجی AI قبل از IPFS و ثبت روی زنجیره
├── data/
│   ├── manifests/                  # فایل‌های سبک متادیتا برای ارجاع (URI/CID/hashes)
│   │   ├── lessons_manifest.json   # لیست درس‌ها با CID، نسخه، سازنده
│   │   ├── quizzes_manifest.json   # لیست کوییزها با CID
│   │   └── exercises_manifest.json # لیست تمرین‌ها با CID
│   ├── samples/                    # نمونه‌های آف‌لاین/توسعه (اختیاری، برای دیو)
│   │   ├── lessons/day1.json
│   │   ├── quizzes/day1.json
│   │   └── exercises/day1.json
│   └── generated/                  # خروجی خام AI پیش از انتشار (local-only, dev)
├── schemas/
│   ├── lesson_schema.json
│   ├── quiz_schema.json
│   ├── exercise_schema.json
│   └── transaction_schema.json     # قرارداد داده برای تراکنش‌ها/پاداش‌ها
├── assets/
│   ├── images/
│   │   ├── web_dev.png
│   │   ├── logo.png
│   │   └── icons/
│   └── fonts/
│       └── iran-sans/
```

---

## Data and auth flow in practice

- **AI generation:**
  - **Trigger:** content_creator_ui.js calls ai_integration.js.
  - **Validation:** schema_validator.js ensures outputs match lesson/quiz/exercise schemas.
  - **IPFS publish:** ipfs_integration.js uploads JSON/image to pinning_client.js, receives a CID.
  - **Manifest update:** Manifests in data/manifests/* are updated with CID, version, and metadata.
  - **On-chain anchor (optional but recommended):** blockchain_integration.js writes the CID hash/URI to ContentRegistry for immutability and provenance.

- **Content retrieval:**
  - **Discover:** UI reads manifests or queries ContentRegistry for latest CID.
  - **Fetch:** gateway_client.js resolves CID via configured IPFS gateways, with **content_cache.db** as client-side cache.
  - **Render:** lesson_ui.js, quiz_ui.js, exercise_ui.js render validated content.

- **Serverless auth with wallets:**
  - **Connect wallet:** authentication.js uses wallet_integration.js to connect (e.g., Polkadot.js or MetaMask).
  - **Identity:** user is identified by public address; actions are signed via private key.
  - **Authorization rules:** authorization.js checks roles/ownership via on-chain state (e.g., isCreator, hasReward).
  - **Protected actions:** auth_middleware.js gates actions like “publish to IPFS” or “claim reward” behind wallet connection.

---

## File changes and responsibilities

- **config.json**
  - **IPFS:** gateway URLs, pinning service API keys, timeout/fallback strategy.
  - **Blockchain:** network names, RPC endpoints, contract addresses, chain IDs.
  - **Security:** allowed content types, maximum sizes, versioning policy.

- **js/logic/ipfs_integration.js**
  - **Upload:** stream-safe JSON and image uploads, receive CIDs, handle retries.
  - **Download:** gateway resolution, integrity checks via hashes, caching.

- **blockchain/contracts/**
  - **ContentRegistry:** map content IDs to CID/URI, version, owner, timestamps.
  - **RewardToken/RewardRegistry:** mint/distribute rewards based on learning events.

- **data/manifests/**
  - **Purpose:** lightweight pointers to decentralized content for fast indexing and UI listing.
  - **Versioning:** track latest CID per content item and previous history.

- **auth and UI**
  - **authentication.js:** wallet connect, signature challenges for session-like UX.
  - **content_creator_ui.js:** one-click flow: generate -> validate -> publish -> anchor -> update manifest.

---

## Critical review of the new structure

- **Strengths**
  - **Clear separation of concerns:** AI, storage (IPFS), blockchain, and UI each have dedicated modules.
  - **Decentralization-first design:** heavy content off-chain with an on-chain anchor ensures integrity without prohibitive costs.
  - **Auditable publishing pipeline:** validation before IPFS, optional on-chain anchoring, and manifests for fast lookup.
  - **Serverless auth:** wallet-based identity removes central auth servers and aligns with Web3 norms.

- **Risks and trade-offs**
  - **Gateway dependencies:** relying on public IPFS gateways can introduce latency or availability issues. Mitigate with multi-gateway fallback and local cache.
  - **Content moderation and updates:** immutability complicates corrections. Address via versioned CIDs, deprecation flags in manifests, and role-based publishing.
  - **User experience friction:** wallet connection can deter non-crypto-native users. Offer a guest mode with read-only access and progressive onboarding.
  - **Security considerations:** exposing pinning API keys in client-side apps is risky. Prefer serverless functions with scoped tokens or restricted capabilities, or use wallet-based delegated publishing where possible.
  - **Complexity creep:** adding blockchain + IPFS increases operational complexity. Keep interfaces minimal, document data contracts, and maintain integration tests.

- **Practical recommendations**
  - **Manifests as first-class:** treat data/manifests/* as your canonical index; the chain is the anchor, IPFS is storage.
  - **Role-based publishing:** only wallet addresses with a “Publisher” role can anchor new content; others can propose drafts.
  - **Light client strategy:** avoid turning users into full nodes; rely on trusted RPCs with verification where feasible.
  - **Monitoring:** add simple telemetry to error_log.txt and optional anonymous metrics to detect gateway failures and UX pain points.