| # 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. | |