This project provides demonstration code for an online adventure store built using .NET 10, Nextjs, and React. The intention of this project is to be used as a sample project for learning and demonstration purposes. It is based on a fictitous e-commerce business called Offgrid that sells adventure goods via it's e-commerce website.
Offgrid is an e-commerce business. It operates as an online retail destination for adventure enthusiasts, offering a curated selection of adventure gear for exploration and outdoor pursuits. It specializes in biking, winter sports, and water sports equipment.
This project will illustrate how to build 2 primary systems in order to fulfill Offgrid business requirements. The 2 primary systems are as follows:
-
Shopping Website
A Nextjs web application frontend with a .NET 10 API backend.
-
Staff Portal
A React web application frontend with a .NET 10 API backend.
This repository follows the Monorepo strategy, and is comprised of design, documentation, application code, and infrastructure code. It showcases a variety of practices for integrating and orchestrating various components of a modern software ecosystem. The objective is to provide a practical, hands-on example that can be used to explore a multitude of concepts, including (and not limited to) the following:
- Provide an organizational design
- Implement specific standard, patterns and practices used across a variety of areas such as Frontend, Backend, Devops, Docker, Git
- Design and build REST based API's using the latest version of C# 14 and .NET 10 Framework
- Design and build a customer facing e-commerce website using Next.js
- Design and build an internal administration application using React
- Provision infrastructure (platform and applications) into containers using Docker Desktop and Docker Compose
- Define devops design using GitHub Actions to setup CI/CD workflows
As mentioned above, this project is intended as a demonstration project to illustrate many different ideas and concepts and evolve it over time. Therefore, for interest sakes, an organizational design has also been provided for Offgrid. The implementation of the various applications and services will take influence from the design but not follow it strictly.
The design documentation is available as follows:
An accompanying guide on Domain Driven Design (DDD) is also provided as part of design documentation:
The project structure will evolve over time. However, this section provides an example of how the project will be generally structured.
offgrid
├── apps # Frontend applications
│ ├── portal-app # React admin portal
│ └── shop-app # Next.js customer shop
│
├── services # .NET backend services
│ ├── Offgrid.slnx
│ ├── portal/
│ │ ├── Offgrid.Portal.slnx
│ │ └── src/ # Portal APIs, domain services, processors
│ └── shop/
│ ├── Offgrid.Shop.slnx
│ └── src/ # Shop API and services
│
├── infra
│ └── local # Local development infrastructure
│ ├── compose.yaml # Main compose file (using include directive for multi-compose-file support)
│ │
│ ├── flyway # Flyway docker config
│ │ └── compose.yaml # Custom Flyway compose file
│ │
│ ├── rabbitmq # RabbitMQ docker config
│ │ └── compose.yaml # Custom RabbitMQ compose file
│ │
│ ├── postgres # Postgres docker config
│ │ └── compose.yaml # Custom Postgres compose file
│ │
│ ├── mongodb # MongoDb docker config
│ │ └── compose.yaml # Custom MongoDb compose file
│ │
│ ├── typesense # Typesense docker config
│ │ └── compose.yaml # Custom Typesense compose file
│ │
│ └── keycloak # Keycloak docker config
│ └── compose.keycloak.yaml # Custom Keycloak compose file
│
├── libs # Shared libraries
│ └── dotnet # .NET shared libraries
│
├── docs
│ ├── design # Architecture and DDD docs
│ ├── decision-registry # Document important project decisions
│ ├── images # Diagrams and visual assets
│ ├── portal # Portal app docs
│ ├── shop # Shop app docs
│ └── standards # Engineering standards
│
├── scripts
├── *.code-workspace
│
└── README.md
Below is a table that summarises the technology stack that has been chosen to implement and manage the various applications and API's.
| Category | Technology | Badge | Description |
|---|---|---|---|
| Languages | C# |  |
Primary backend language for robust, type-safe enterprise applications |
| TypeScript |  |
Typed superset of JavaScript used for frontend, Node.js backend, and tooling | |
| Bash |  |
Shell scripting for automation, CI/CD scripts, and local dev workflows | |
| Backend & Frameworks | .NET 10 |  |
Modern cross-platform framework for high-performance APIs, services & microservices |
| Node.js |  |
JavaScript runtime for server-side logic, real-time features & lightweight APIs | |
| Next.js |  |
React framework with SSR, SSG, API routes & full-stack capabilities | |
| React |  |
Component-based UI library powering interactive frontends | |
| Identity & Auth | Keycloak |  |
Open-source identity & access management (OIDC/OAuth2/SAML, SSO, user federation) |
| Databases & Search | PostgreSQL |  |
Powerful, standards-compliant relational SQL database with strong ACID guarantees |
| MongoDB |  |
Flexible document-oriented NoSQL database for schemaless or semi-structured data | |
| Typesense |  |
Fast, typo-tolerant, open-source search engine (Algolia alternative) | |
| Messaging | RabbitMQ |  |
Reliable message broker for queues, pub/sub, task distribution & microservices decoupling |
| Migrations | Flyway (Red Hat) |  |
Version-controlled SQL-based database migrations (schema evolution tool) |
| DevOps & Infra | Docker / Compose |  |
Containerization & multi-container local orchestration for consistent environments |
| Terraform |  |
Infrastructure as Code for provisioning & managing cloud resources declaratively | |
| GitHub Actions |  |
CI/CD pipelines, automation workflows & deployment orchestration directly in GitHub | |
| Tools | Git |  |
Distributed version control system for source code management |
| VS Code |  |
Lightweight, extensible code editor with excellent support for this entire stack |
The following diagram provides a very high level overview of where various technology stack choices are used:
- Next.js and Typescript are used to build the public facing shopping website
- React and Typescript are used to build the internal facing staff portal that manages the backoffice
- C# 14 .NET 10 is used to build API's and Background Services (Workers/Producers/Consumers)
- RabbitMQ is used as a message bus
- Keycloak provide authentication and authorization to the web applications and API's
- MongoDB is used for the product catalog
- Typesense is used for searching products
- Postgresql is used for data requiring ACID (Atomicity, Consistency, Isolation, Durability) compliance
- Redgate Flyway is used to manage and version database migrations
- Docker and Docker Compose are used to manage and host infrastructure services, applications, and API's
- Bash script are used to provide utility scripts to help manage and automate tasks
The following software will be required to be installed on your device in order to open and run the applications and API's:
- Node.js 24
- .NET 10
- Git
- Windows Subsystem for Linux (WSL) to use shell scripts. Alternatively, if on Windows, Git Bash.
- Docker Desktop
📜 NOTE: Run the following script from your terminal to get a "Tool Installation Report".
The script checks against a list of required and optional tools to verify the installation status of each tool.
➜ chmod +x ./tool-installation-check.sh
➜ ./tool-installation-check.sh
Checking installed tools...
=========================== Tool Installation Report ===========================
Required Tools:
✔️ node: Installed (Version: 24.12.0)
✔️ git: Installed (Version: 2.51.2.windows.1)
✔️ docker: Installed (Version: Docker version 29.1.3, build f52814d)
✔️ npm: Installed (Version: 11.6.4)
✔️ dotnet: Installed (Version: 10.0.102)
Optional Tools:
✔️ az: Installed
✔️ terraform: Installed
✔️ aws: Installed (Version: 2.32.30)
✔️ vim: Installed (Version: 9.1)
✔️ jq: Installed (Version: jq-1.8.1)
✔️ gh: Installed (Version: 2.83.2)
✔️ yq: Installed (Version: yq (https://github.com/mikefarah/yq/) version v4.48.1)
-
Specifies the standard convention for writing Git commit messages.
-
Provides details on the approach and standards relating to git setup and use.
-
Follow the project standard for recording important/critical project decisions. An important/critical decision, put simply, is one that once made is difficult to change after the fact. For example, decisions relating to technical, strategic, or operational concerns.
- See README
- See Decision SOP
- See Decision Template
- See Decision Summary
- Repo-level guide: ./agents.md
- App guides: ./apps/shop-app/agents.md, ./apps/portal-app/agents.md
- Service guides: ./services/agents.md, ./services/shop/agents.md, ./services/portal/agents.md
- .NET Lib guides: ./libs/dotnet/agents.md
- Infra guide: ./infra/agents.md
- Docs guide: ./docs/agents.md
- Helper script: ./scripts/show-agents.sh
- Copilot instructions: ./.github/copilot-instructions.md
Important
Please take note of the comprehensive 📋 onboarding document.
The onboarding document is completely generated using GitHub Copilot (Grok Code Fast 1/Claude Opus 4.6) with some minor tweaks between the different AI models.
Find documentation here:
-
Infra Docs
-
Portal Design Docs
-
Shop Design Docs
-
App Docs
- shop-app: ./apps/shop-app/README.md
- portal-app: ./apps/portal-app/README.md
-
Service Docs
- shop-api: ./services/shop/README.md
- portal-api: ./services/portal/README.md
-
Other Docs
Important
-
Run these commands from a Git Bash / POSIX shell (on Windows use Git Bash or WSL).
-
Ensure that all scripts have execute (
x) permissions. Runchmod +x my-script.shto add execute permissions.
# verify tool installation
./scripts/tool-installation-check.sh
# verify environment setting files are created
./scripts/env-file-check.sh
# verify host file entries
./scripts/host-file-entry-check.sh
Alternatively, use the following wrapper script that runs all prereq scripts from above:
# run all prerequisite checks
./scripts/prereq-check.sh
This section explains how to run the required infrastructure services locally in Docker. For example:
- Postgres
- Keycloak
- Flyway
Important
-
Run these commands from a Git Bash / POSIX shell (on Windows use Git Bash or WSL).
-
Ensure that all scripts have execute (
x) permissions. Runchmod +x my-script.shto add execute permissions.
# start infrastructure stack
./infra/local/scripts/compose.sh up
# verify infrastructure stack
./infra/local/scripts/compose.sh ps
# run flyway migrations
./infra/local/scripts/flyway.sh migrate
Alternatively, use the following wrapper scripts:
# run all infrastructure services (postgres, keycloak, etc) locally
./scripts/run-infra-services.sh
# run shop services (app, api) in Docker (optional)
./scripts/run-shop-services.sh
To access various infrastructure services using their respective clients, use one of the following options:
-
Shell scripts
keycloak cli: kcadmpostgres cli: psqlrabbitmq cli: rabbitmqadm
-
Windows Terminal script:
# open infra clients: ./scripts/wt-infra.psq pwsh -file .\wt-infra.psq
This section explains how to run the shop services locally in the terminal. For example:
-
Shop Api (.NET 10)
dotnet watch run --project ./services/shop/src/Offgrid.Shop.Api/Offgrid.Shop.Api.csproj
-
Shop App (Nextjs)
npm install --prefix ./apps/shop-app npm run dev --prefix ./apps/shop-app
Alternatively, run a powershell script to lauch all shop apps/services in a single terminal within separate panes:
# open shop apps/services: ./scripts/wt-shop.ps1
pwsh -file .\wt-shop.ps1
This section explains how to run the shop services locally in Docker. For example:
- shop-app (nextjs)
- shop-api (.NET 10)
Important
-
Run these commands from a Git Bash / POSIX shell (on Windows use Git Bash or WSL).
-
Ensure that all scripts have execute (
x) permissions. Runchmod +x my-script.shto add execute permissions.
# start infrastructure stack
./infra/local/scripts/compose.sh up
# verify infrastructure stack
./infra/local/scripts/compose.sh ps
# run flyway migrations
./infra/local/scripts/flyway.sh migrate
Alternatively, use the following wrapper scripts:
# run all infrastructure services (postgres, keycloak, etc) locally
./scripts/run-infra-services.sh
# run shop services (app, api) in Docker (optional)
./scripts/run-shop-services.sh
This section explains how to run the portal services locally in the terminal. For example:
-
Portal Api (.NET 10)
dotnet watch run --project ./services/portal/src/Offgrid.Portal.Api/Offgrid.Portal.Api.csproj
-
Portal Customer Outbox Processor (.NET 10)
dotnet watch run --project ./services/portal/src/Offgrid.Portal.Customers.OutboxProcessor/Offgrid.Portal.Customers.OutboxProcessor.csproj
-
Portal Customer Event Processor (.NET 10)
dotnet watch run --project ./services/portal/src/Offgrid.Portal.Customers.EventProcessor/Offgrid.Portal.Customers.EventProcessor.csproj
-
Portal App (Reactjs)
npm install --prefix ./apps/portal-app npm run dev --prefix ./apps/portal-app
For Windows users, open up Powershell in Windows Terminal and run the following commands to launch apps in a single terminal window within separate panes:
# open portal apps/services: ./scripts/wt-portal.ps1
pwsh -file .\wt-portal.ps1
Access the apps and services via the following links:
-
Shop App Website (http://localhost:3000)
- See ./apps/shop-app/README.md for more details
-
Shop API (http://localhost:7000)
- See ./services/shop/README.md for more details
-
Portal App Website (http://localhost:4000)
- See ./apps/portal-app/README.md for more details
-
Portal API (http://localhost:7001)
- See ./services/portal/README.md for more details
-
Keycloak Shop Account (http://localhost:8080/realms/offgrid-public/account)
-
Keycloak Portal Account (http://localhost:8080/realms/offgrid-internal/account)
Connect to infrastructure services:
See Infrastructure README (./infra/local/README.md)
-
Postgres psql (./infra/local/scripts/psql.sh):
./infra/local/scripts/psql.sh -
Flyway (./infra/local/scripts/flyway.sh):
./infra/local/scripts/flyway.sh info -
RabbitMQ Admin:
./infra/local/scripts/rabbitmqadmin.sh -
Keycloak Admin:
./infra/local/scripts/kcadm.sh
Note
Take note of the Visual Studio Tasks that have been defined for this project.
- See tasks.json
- Press
Ctrl+Shift+bto open build menu that displays tasks
A summary of the tasks.json is provided as follows:
- infra
bash: compose up— Start the local infra stack via the compose helper script.bash: compose down— Stop and remove the local infra stack via the compose helper script.bash: compose ps— Show status of local infra containers.bash: compose logs— Show logs for a selected service (prompted).bash: compose up-recreate— Recreate a selected service (prompted).bash: psql— Open a Postgres CLI session using the repo script.bash: rabbitmqadmin— Run RabbitMQ admin CLI using the repo script.bash: mongosh— Run Mongo shell CLI using the repo script.bash: flyway— Run Flyway command (prompted).
- shop apps/services
dotnet: run shop-api— Run the Shop API with dotnet watch.npm: run shop-app— Run the Shop frontend app in dev mode.
- portal apps/services
dotnet: run portal-api— Run the Portal API with dotnet watch.dotnet: run portal-outbox-processor— Run the Portal Customers Outbox Processor with dotnet watch.dotnet: run portal-event-processor— Run the Portal Customers Event Processor with dotnet watch.npm: run portal-app— Run the Portal frontend app in dev mode.
I use SemVer for versioning. For the versions available, see the tags on this repository.
-
This is the initial release of Offgrid, a reference/demo e-commerce project showcasing a modern, monorepo-based online adventure gear store (biking, winter & water sports equipment). Built with .NET 10 (C# 14) for the backend APIs, Next.js + React + TypeScript for the customer-facing shopping site, and Keycloak for authentication, it demonstrates clean architecture, Domain-Driven Design (DDD), and full local development setup via Docker Compose.
Key highlights include:
- Customer shopping frontend (Next.js) + .NET API
- PostgreSQL + Flyway migrations, Keycloak (OIDC/OAuth2)
- Monorepo layout: apps/, libs/, infra/, docs/, scripts/
- One-command startup scripts & prerequisite validation
- Extensive DDD & architecture documentation
- No binaries/assets attached — source code & Docker only
See release notes.
See the code.
See design docs.
-
The focus of this release is to establish an MVP (Minimum Viable Product) for a backoffice administration app called Portal.
Key highlights include:
- Restructure: A major restructure of monorepo to help simplify understanding and development.
- Portal App: Customer detail page, customer list with filters, pagination, and improved navigation.
- Portal API: Full customer management endpoints (list, detail, suspend, reinstate), outbox pattern, event processor, and robust validation.
- Infrastructure: Outbox/event processor, RabbitMQ integration, improved Flyway migrations, and enhanced local dev scripts.
- Shared Libraries: New DDD/domain abstractions, enum utilities, pagination, and messaging contracts.
- Docs & Onboarding: Comprehensive agent guidance, onboarding, and design documentation.
See release notes.
See the code.
See design docs.
- Douglas Minnaar - Sole and primary maintainer - drminnaar