diff --git a/README.md b/README.md index 0e8045a..de77ec9 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ ChainLearn is a Stellar-based AI-powered learning platform that rewards learners with on-chain tokens and verifiable credentials. This repository contains the canonical documentation for all ChainLearn services, smart contracts, APIs, and architectural decisions. +--- + ## Quick Links | Section | Description | @@ -9,20 +11,90 @@ ChainLearn is a Stellar-based AI-powered learning platform that rewards learners | [Architecture Overview](architecture/overview.md) | System design, repo structure, tech stack | | [Data Flow](architecture/data-flow.md) | End-to-end flow from enrollment to credential | | [Smart Contracts](architecture/smart-contracts.md) | Contract design decisions and rationale | -| [API Reference](api/) | OpenAPI specs for all services | +| [API Reference](api/) | OpenAPI specs for all platform services | | [Contract Docs](contracts/) | Learn Token, Credential NFT, Progress Tracker | -| [Guides](guides/) | Local dev, deployment, contributing | +| [Guides](guides/) | Local development, deployment, contributing | | [Decision Records](decisions/) | Architecture Decision Records (ADRs) | -## Platform Overview +--- + +## Directory Structure Overview + +The documentation is organized into focused directories: + +```text +chainlearn-docs/ +├── api/ # OpenAPI / Swagger specifications and REST endpoints +├── architecture/ # System design, data flow diagrams, and contract rationale +├── contracts/ # Soroban contract references (Learn Token, NFT, Progress) +├── decisions/ # Architectural Decision Records (ADRs) & adr-template.md +├── guides/ # Guides for setup, local dev, deployments, and contributing +└── README.md # Documentation home and contributor guidelines +``` + +- **`architecture/`**: High-level platform design, component interactions, and data flow models. +- **`api/`**: OpenAPI 3.0+ specifications describing REST endpoints for `chainlearn-api` and `chainlearn-ai`. +- **`contracts/`**: Specification, storage schemas, and entry point references for Soroban contracts. +- **`decisions/`**: Architecture Decision Records (ADRs) capturing major architectural trade-offs. +- **`guides/`**: Practical guides for onboarding new contributors, local testing, and platform deployment. + +--- + +## Architecture Decision Records (ADR) Process + +We use Architecture Decision Records to capture significant technical choices, their context, and their consequences. + +### Existing ADRs + +- **[ADR-001: Soroban over Ethereum](decisions/adr-001-soroban-over-ethereum.md)** — Decision to deploy smart contracts on Stellar/Soroban instead of EVM. +- **[ADR-002: SEP-41 Token Standard](decisions/adr-002-sep41-token-standard.md)** — Adoption of the SEP-41 token interface for learning rewards. +- **[ADR-003: AI Provider Selection](decisions/adr-003-ai-provider-selection.md)** — Rationale for selecting Cohere as the primary LLM provider. + +### How to Propose a New ADR -ChainLearn combines three technologies: +1. **Copy the Template:** Copy [`decisions/adr-template.md`](decisions/adr-template.md) to a new file in `decisions/`: + ```bash + cp decisions/adr-template.md decisions/adr-004-.md + ``` +2. **Assign the Next Number:** Check the existing files in `decisions/` and increment the three-digit number (`004`, `005`, etc.). +3. **Fill Out All Sections:** + - **Context:** What problem are we solving? What forces are at play? + - **Decision:** What is the proposed change or architectural direction? + - **Consequences:** Positive outcomes, trade-offs, and risks introduced. +4. **Initial Status:** Set the status to `Proposed`. +5. **Open a Pull Request:** Submit a PR with the title `[ADR] ` and request reviews from core maintainers. Once approved and merged, update status to `Accepted`. -1. **AI-generated content** -- Courses, quizzes, and feedback are generated by Cohere's language models, ensuring fresh and personalized learning material. -2. **Stellar blockchain** -- Rewards (SEP-41 tokens) and credentials (NFTs) are issued on-chain via Soroban smart contracts, giving learners portable, verifiable proof of achievement. -3. **Traditional web stack** -- A React frontend, Node.js API, and PostgreSQL database handle the user experience, authentication, and content management. +--- -## Repository Map +## How to Add New Documentation + +1. **Identify the Proper Location:** + - Architecture concepts -> `architecture/` + - How-to guides or tutorials -> `guides/` + - Contract interface changes -> `contracts/` + - Architectural decisions -> `decisions/` +2. **Naming Convention:** Use lowercase kebab-case for filenames (e.g., `local-development.md`, `indexer-setup.md`). +3. **Internal Linking:** Use relative markdown links (`[Link Text](../section/file.md)`) so links work on both GitHub and static doc sites. +4. **Update Indexes:** When adding a new document, add a link in this `README.md` or the corresponding directory index. + +--- + +## Diagram Tooling & Conventions + +We use **[Excalidraw](https://excalidraw.com)** for architecture diagrams and visual workflows: + +- **Source Files:** Always check in the editable `.excalidraw` file alongside the exported asset so future contributors can update it. +- **Export Format:** Export diagrams as `.svg` (preferred for vector scalability) or high-resolution `.png`. +- **Location:** Place diagram assets in the same directory as the document referencing them or in an `assets/` / `images/` subfolder. + +--- + +## Platform Overview & Ecosystem Repositories + +ChainLearn combines three core technologies: +1. **AI-generated content** — Courses, quizzes, and feedback generated by Cohere's language models. +2. **Stellar blockchain** — Rewards (SEP-41 tokens) and credentials (NFTs) issued via Soroban smart contracts. +3. **Traditional web stack** — React frontend, Node.js API, and PostgreSQL database. The ChainLearn platform spans seven repositories: @@ -33,16 +105,20 @@ The ChainLearn platform spans seven repositories: | `chainlearn-ai` | Python AI service (Cohere integration) | | `chainlearn-contracts` | Soroban smart contracts (Rust) | | `chainlearn-indexer` | Event indexer for on-chain data | -| `chainlearn-docs` | This documentation | +| `chainlearn-docs` | Platform documentation (this repository) | | `chainlearn-infra` | Terraform + Docker infrastructure | -## Getting Started +--- + +## Contributing + +We welcome community contributions to improve our documentation! -New to ChainLearn? Start here: +- Read the [Contributing Guide](guides/contributing.md) for style conventions and submission steps. +- Verify all markdown links locally before opening a pull request. +- Keep documentation clear, concise, and accessible to developers of varying experience levels. -1. Read the [Architecture Overview](architecture/overview.md) to understand the system -2. Follow the [Local Development Guide](guides/local-development.md) to set up your environment -3. Review the [Contributing Guide](guides/contributing.md) before submitting changes +--- ## License