From 268dbdccda2f4215dc01df7fbd5bbdf2eb3ae125 Mon Sep 17 00:00:00 2001 From: Michael Geers Date: Sun, 16 Jun 2024 13:38:00 +0200 Subject: [PATCH] add blueprint tech details --- README.md | 109 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 88 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 5c5913e..b199c90 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,11 @@ The Tractor Store is a template to experiment with micro frontend architecture. Goal is to create a real world application where developers can experiment with different integration techniques. -The idea is similar to [TodoMVC](http://todomvc.com/) or [Movies](https://tastejs.com/movies/), but with a focus on micro frontends. +The idea is similar to [TodoMVC](http://todomvc.com/) or [Movies](https://tastejs.com/movies/), but with a focus on micro frontends. Visit [micro-frontends.org/tractor](https://micro-frontends.org/tractor-store/) to learn more. -## About this project +**Live Demo:** [blueprint.the-tractor.store](https://blueprint.the-tractor.store) + +## About This Project - Three systems: Explore, Decide, Checkout are established along the customer journey (buying process) - Team missions @@ -21,7 +23,7 @@ The idea is similar to [TodoMVC](http://todomvc.com/) or [Movies](https://tastej - Styling is provided in the blueprint. It's not the focus of this project. - Static assets (images, fonts, helpers, ...) are provided. They can be copied or linked to directly ([CDN](https://blueprint.the-tractor.store)). -## Design principals +## Design Principals - Each system can be developed and deployed independently by different teams - The freedom to change a systems technology stack without affecting the others must be guaranteed @@ -29,7 +31,7 @@ The idea is similar to [TodoMVC](http://todomvc.com/) or [Movies](https://tastej - Loose coupling: Systems should be able to function independently of each other as best as possible - Provide a way to run the entire application locally for development and testing -## Implementation choices +## Implementation Choices - All described features must be implemented. - The concrete implementation is up to you (frontend framework, style handling, etc.) @@ -40,7 +42,7 @@ The idea is similar to [TodoMVC](http://todomvc.com/) or [Movies](https://tastej - Bonus objective #1: Extract shared UI components (e.g. the Button) into a shared pattern library. - Bonus objective #2: The Explore team is getting too big. A new "Inspire" team should be created to take care of product recommendations. Migrate this function to a standalone fourth system. -## Goal of the project +## Goal of This Project There is no one-size-fits-all solution for micro frontends. The goal of this project is to provide a central place, where different micro frontend integration techniques can be compared and evaluated. @@ -53,14 +55,7 @@ The goal of this project is to provide a central place, where different micro fr - Share knowledge and learnings with the community - Provide a blueprint for others to experiment with a specific micro frontends tech stack -## Implementation gallery - -- Fork the blueprint or any other implementation -- Submit a an issue with a link to your implementation (github repo) -- Describe you tech stack and integration techniques using the issue template -- Extra points if you provide a hosted version of your implementation - -## Anatomy of the project +## Features ### Boundaries 📄 @@ -70,11 +65,11 @@ The goal of this project is to provide a central place, where different micro fr - 📄 Stores - 🧩 Header (🔴🟢🟡 every page, except checkout) - 🧩 Footer (🔴🟢🟡 every page) - - 🧩 Recommendations (🔴 home, 🟢 product, 🟡 cart) + - 🧩 Recommendations (🔴 home, 🟢 product detail, 🟡 cart) - 🧩 Store Picker (🟡 checkout) - 🟢 Decide - 📄 Product detail -- 🟡 Buy +- 🟡 Checkout - 📄 Cart - 📄 Checkout - 📄 Thank you @@ -90,9 +85,81 @@ The goal of this project is to provide a central place, where different micro fr - Potential client-side interactions (variant change, remove from cart, form validation) - Nested integration (page > header > mini cart) - [Bonus] Shared UI components / pattern library (button) - -### Infrastructure 🏗️ - -- Deployment -- Integration service -- End-to-end tests (planned) +- [Bonus] Migrate recommendations to a new system (Team Inspire) + +### Data Structures 💽 + +Each team has its own data model optimized for their tasks. + +- 🔴 Team Explore + - Categories + - Products (no variants) + - Stores + - Recommendations + - Recommendable variants + - Color-based algorithm +- 🟢 Team Decide + - Products + - Variants (sku, name, highlights) +- 🟡 Team Checkout + - Line items + - Variant (sku, name, price) + - Inventory + - Cart state (cookie, sku, quantity) + +Use the individual `database.json` files as a data source for each system. +You can render the data directly or build a REST, GraphQL, or other API on top of it. +Check out the [preact implementation](https://github.com/neuland/tractor-store-preact) for an already implemented REST API. + +**Note:** This repository also contains a global `products.js` and individual `import.js` files. +They contain raw product data and conversion logic to generate the individual `database.json` files. +Similar to a data-replication mechanism in a real-world project. You can ignore these files. + +## About the Blueprint Implementation + +The blueprint is deliberately kept simple and unopinionated to make it easy to build specific implementations based on it. + +The blueprint does is a **modular monolith** and not a micro frontend architecture. +It has to be deployed as a single unit. +However, the code and data structured are structured in a way that it can be easily split per-team applications. + +| Aspect | Solution | +| -------------------------- | ------------------------------- | +| 🛠️ Frameworks, Libraries | Pure JS, no dependencies | +| 📝 Rendering | SSR-only | +| 🐚 Application Shell | None | +| 🧩 Client-Side Integration | None | +| 🧩 Server-Side Integration | None (template includes) | +| 📣 Communication | Custom Events | +| 🗺️ Navigation | MPA | +| 🎨 Styling | Plain CSS | +| 🍱 Design System | None | +| 🔮 Discovery | None | +| 🚚 Deployment | Serverless (Cloudflare Workers) | +| 👩‍💻 Local Development | Node.js, [hono] | + +[hono]: https://hono.dev + +## How To Run Locally + +Clone this repository and run the following commands: + +```bash +git clone https://github.com/neuland/tractor-store-blueprint.git tractor-store-blueprint +cd tractor-store-blueprint +``` + +Install and start dev mode: + +```bash +npm install +npm run dev +``` + +Open http://localhost:3000 in your browser to see the running application. +Dev-Mode watches for changes in your server-side code. +It does not watch for changes in your client-side JS and CSS code. This is built once on start. + +## Contribute and Build Your Own + +Visit the [Tractor Store Website](https://micro-frontends.org/tractor-store/#contribute) for more details.