This document introduces the RealWorld project and its ecosystem architecture. It explains the purpose of this repository, its structure, and how the three main components (API specification, reference implementation, and documentation) work together to enable a plug-and-play ecosystem of interchangeable frontend and backend implementations.
For detailed information about specific components:
RealWorld is a project that demonstrates how to build real-world applications (specifically, a Medium.com clone called "Conduit") using various frameworks and technology stacks. Unlike simple "todo" demos, RealWorld implementations are full-featured applications with authentication, CRUD operations, pagination, and social interactions.
The key innovation is plug-and-play modularity: any frontend implementation can work with any backend implementation because they all adhere to the same API specification.
The Problem RealWorld Solves:
| Traditional Demos | RealWorld |
|---|---|
| Simple todo apps that don't show real-world complexity | Full-featured Medium.com clone with authentication, profiles, articles, comments |
| Framework-specific examples that can't be compared | 150+ implementations across different frameworks that can be directly compared |
| No interoperability between different implementations | Any frontend works with any backend via standardized API |
Sources: README.md1-42 apps/documentation/src/content/docs/introduction.mdx1-36
The RealWorld ecosystem consists of over 150 implementations spanning multiple categories. This repository serves as the central hub that enables the entire ecosystem.
Key Architectural Principle: The OpenAPI specification (apps/documentation/src/assets/swagger.json1-1143) serves as the single source of truth that enables modularity. All implementations must adhere to this specification to participate in the ecosystem.
Sources: README.md5-11 apps/documentation/src/content/docs/introduction.mdx7-12 apps/documentation/src/assets/swagger.json1-43
This repository is organized as a monorepo containing three primary sub-systems:
| Path | Purpose | Key Files |
|---|---|---|
apps/api/ | Node.js reference implementation | package.json, server/routes/, prisma/schema.prisma |
apps/documentation/ | Astro-based documentation site | astro.config.mjs, src/content/docs/ |
api/ | API specification and test collection | swagger.json, Conduit.postman_collection.json, run-api-tests.sh |
.github/workflows/ | CI/CD automation | api.yaml, api-testing-playwright.yaml, codeql.yml |
Makefile | Build orchestration | Targets for setup, test, build, clean |
Sources: README.md1-42 apps/documentation/astro.config.mjs1-182
The OpenAPI 3.0.1 specification at apps/documentation/src/assets/swagger.json1-1143 defines the complete API contract that all implementations must follow.
Specification Overview:
Defined Endpoints: 15 total across 6 categories
Data Models: User, Profile, Article, Comment, Tag, with validation rules
Authentication: JWT token-based, passed via Authorization header
For complete endpoint details, see Endpoints Reference.
Sources: apps/documentation/src/assets/swagger.json1-1143 apps/documentation/src/content/docs/specifications/backend/introduction.md1-10
The reference implementation at apps/api/ demonstrates best practices for building a compliant RealWorld backend.
Technology Stack:
| Component | Technology | Purpose |
|---|---|---|
| Framework | Nitro | Server-side routing and handlers |
| ORM | Prisma | Type-safe database access |
| Database | SQLite | Development database (dev.db) |
| Auth | jsonwebtoken + bcryptjs | JWT generation and password hashing |
Key Files:
The reference implementation is deployed at https://api.realworld.show for public use with strong account isolation.
For implementation details, see Reference Implementation.
Sources: README.md34-35 apps/documentation/src/content/docs/specifications/frontend/api.md1-55
The documentation site at apps/documentation/ is built with Astro and the Starlight theme to provide comprehensive guidance for developers creating new implementations.
Site Structure (from astro.config.mjs):
Build System:
removeMdExtension() for cleaner URLs (apps/documentation/astro.config.mjs42-53)For documentation build details, see Documentation Site.
Sources: apps/documentation/astro.config.mjs1-182 apps/documentation/src/content/docs/introduction.mdx1-36
The testing infrastructure ensures that implementations adhere to the API specification through automated validation.
Postman Collection Architecture:
Test Coverage:
| Category | Endpoints Tested |
|---|---|
| Authentication | /users, /users/login, /user (GET/PUT) |
| Profiles | /profiles/{username}, /profiles/{username}/follow |
| Articles | /articles, /articles/{slug}, /articles/feed |
| Comments | /articles/{slug}/comments, /articles/{slug}/comments/{id} |
| Favorites | /articles/{slug}/favorite |
| Tags | /tags |
The test collection maintains state across requests (storing JWT tokens, article slugs) to validate end-to-end workflows.
For testing details, see Testing Infrastructure.
Sources: apps/documentation/src/content/docs/specifications/backend/postman.md1-10 apps/documentation/src/content/docs/specifications/backend/introduction.md5-7
The Makefile at the repository root orchestrates all build, test, and development workflows across both the API and documentation sub-projects.
Key Make Targets:
| Target | Purpose |
|---|---|
reference-implementation-setup | Install dependencies, generate Prisma client, prepare database |
reference-implementation-test-with-postman | Start API server and run Newman tests |
documentation-build | Build static documentation site |
documentation-preview | Preview documentation locally |
For complete build system documentation, see Build System & Workflows.
Sources: README.md1-42
The reference implementation is deployed at https://api.realworld.show/api (apps/documentation/src/assets/swagger.json37-40).
Usage Characteristics:
A live demo is available at https://demo.realworld.show that connects to the public API, demonstrating the full application functionality.
Sources: README.md34-35 apps/documentation/src/content/docs/specifications/frontend/api.md36-44
make reference-implementation-setup to set up the APImake documentation-setup to set up the docs siteFor contribution guidelines, see Contributing & Community.
Sources: apps/documentation/src/content/docs/implementation-creation/introduction.md1-20 README.md23-36
The project has active maintainers including c4ffein (demo website) and Manuel Vila (CodebaseShow website creator).
Sources: README.md15 README.md38-41 apps/documentation/src/content/docs/community/resources.md1-16
Refresh this wiki