GitHub Clean Arch React

A React + TypeScript application that explores the Clean Architecture approach for front‑end apps. It consumes the public GitHub APIs and showcases modular design, dependency inversion, and testability through a clean, layered structure.

View Demo · Report Bug · Request Feature

---

Table of Contents

• About the Project
• Features
• Architecture
  • Layers
  • Factories \u0026 Dependency Injection
• Tech Stack
• Project Structure
• Getting Started
  • Prerequisites
  • Installation
  • Configuration \u0028optional\u0029
  • Run
  • Test
• Contributing
• Roadmap
• Acknowledgements
• Contact

---

About the Project

This repository demonstrates how to build a React application using Clean Architecture and design patterns that favor modularity, separation of concerns, and easy maintainability.
It integrates with the GitHub REST APIs to present real data while keeping the core rules of the app isolated from frameworks and external details.

(back to top)

Features

• Clean, layered architecture with a clear separation of concerns
• Factory-based Dependency Injection for easy swapping of implementations
• Strong typing (TypeScript) and unit tests (Jest)
• Simple, real-world integration with GitHub APIs
• Scalable project structure designed for growth

(back to top)

Architecture

The goal is to keep the business rules independent of frameworks and UI details. External concerns—such as HTTP clients or storage—live at the boundaries and can be replaced without touching the core.

+--------------------+
|   Presentation     |  ← React components, hooks, view-models
+----------+---------+
           |
           v
+----------+---------+
|    Application     |  ← orchestrates use cases, input/output ports
+----------+---------+
           |
           v
+----------+---------+
|     Domain         |  ← entities, business rules, pure logic
+----------+---------+
           |
           v
+----------+---------+
|      Data/Infra    |  ← implementations (GitHub API, storage, http)
+--------------------+

Layers

• Domain: Entities and business logic.
• Application (EntryPoint/Main): Use cases and input/output ports. In this project, the “Main” layer wires everything together.
• Data: Concrete repositories and mappers (e.g., GitHub API repositories).
• Infra: External details (HTTP client, persistence, framework integrations).
• Presentation: UI (React), containers, and adapters.

Factories & Dependency Injection

The Factory Pattern is used to wire dependencies without coupling the Presentation layer to concrete implementations.

// Domain
export interface UserRepository {
  getUserById(id: string): Promise<User>;
}

// Data
export class UserDataRepository implements UserRepository {
  async getUserById(id: string): Promise<User> {
    // Fetch from GitHub API (or any source)
    // map/validate into Domain entity
    return { /* ... */ } as User;
  }
}

// Main / factories
export const makeUserRepository = (): UserRepository => new UserDataRepository();

// Presentation
const UserRepoProvider: React.FC = () => {
  return <UserRepo repo={makeUserRepository()} />;
};

For more reading: Clean Architecture overview by Mehdi Hadeli
https://github.com/mehdihadeli/awesome-software-architecture/blob/main/docs/clean-architecture.md

(back to top)

Tech Stack

• React 18+ (UI)
• TypeScript 5+ (type safety)
• Jest (unit tests)
• Node.js 18+ (tooling)
• Optional: ESLint and Prettier for code quality/formatting

(back to top)

Project Structure

A suggested structure that follows Clean Architecture principles:

src/
├─ domain/                 # Core entities & business rules
│  ├─ entities/
│  ├─ value-objects/
│  └─ services/
├─ application/            # Use cases, ports (interfaces) and orchestrators
│  ├─ ports/
│  └─ usecases/
├─ data/                   # Concrete repositories, mappers
│  ├─ repositories/
│  └─ mappers/
├─ infra/                  # External concerns (http, storage, frameworks)
│  ├─ http/
│  └─ config/
├─ presentation/           # React UI, components, pages, hooks
│  ├─ components/
│  ├─ pages/
│  └─ hooks/
└─ main/                   # Composition root (factories, providers)
   └─ factories/

(back to top)

Getting Started

Prerequisites

• Node.js 18+
• npm (or your preferred package manager)

npm install npm@latest -g

Installation

# Clone
git clone https://github.com/MarcoRhayden/github-clean-arch-react
cd github-clean-arch-react

# Install deps
npm install

Run

npm start

Your app should be available at the URL printed by your dev server.

Test

# Run unit tests
npm test

# Coverage
npm test -- --coverage

(back to top)

Acknowledgements

• 📖 Best README Template
• 📖 Clean Architecture Overview

Contact

• Website: https://arkansoftware.com/
• Demo: https://github-cleancode-quest.netlify.app/
• Issues: https://github.com/MarcoRhayden/github-clean-arch-react/issues

(back to top)