Skip to content

docs: expand README with directory structure, ADR process, and diagram tooling #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shobhamerabacha-star wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: expand README with directory structure, ADR process, and diagram tooling #5

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 90 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,27 +2,99 @@

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 |
|---------|-------------|
| [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-<short-descriptive-title>.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] <Title>` 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:

Expand All @@ -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

Expand Down