diff --git a/README.md b/README.md index f509ddd92..64cdcb60c 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,57 @@ --- -> **All you need to start your web3 service, 🔋 included.** +> **Offline: Next-gen Consumer Brand Interaction Platform** -> **This project has been deployed using [Vercel](https://vercel.com/), [Hasura Cloud](https://hasura.io/cloud/) and [Railway.app](https://railway.app/). You can check it out [here](https://www.offline.app/). For more information about the deployment process, check the [deployment section](./production/README.md) 🚀.** +## Table of Contents -## Quick install +1. [Project Overview](#project-overview) +2. [Architecture](#architecture) +3. [Quick Install](#quick-install) +4. [Project Structure](#project-structure) +5. [The Stack](#the-stack) +6. [Libraries](#libraries) +7. [Testing](#testing) +8. [NX Workspace](#nx-workspace) +9. [Environment Configuration](#environment-configuration) +10. [Troubleshooting](#troubleshooting) +11. [Services](#services) + +## Project Overview + +Offline is an innovative platform designed to revolutionize brand-customer interactions through user-centric applications leveraging blockchain and NFT technologies. The project consists of three main applications: + +1. **Marketplace** (`apps/web`): The user-facing app where customers can browse and purchase tickets for events offered by organizers. This serves as the main entry point for consumers to interact with brands and access exclusive experiences. + +2. **Back-office** (`apps/back-office`): A comprehensive management interface for organizers to create and manage their events, smart contracts, and analyze performance metrics. This empowers brands to easily create and manage their offerings on the Offline platform. + +3. **Unlock** (`apps/unlock`): An iframe app that allows users to connect their Offline smart contract wallet across various platforms outside of Offline. This includes integration with Shopify stores for token-gating campaigns, expanding the utility of Offline's blockchain-based assets. + +
+Offline Platform Architecture
+ +## Architecture + +The Offline Marketplace Monorepo employs a microservices architecture with the following key components: + +- **Hasura**: Serves as the central data layer, providing a GraphQL API for all three Next.js applications. This ensures consistent data access and management across the platform. + +- **Next.js Apps**: + + 1. Marketplace (`apps/web`) + 2. Back-office (`apps/back-office`) + 3. Unlock (`apps/unlock`) + + Each app is built using Next.js 14 with the App Router, ensuring optimal performance and SEO capabilities. + +- **Blockchain Integration**: Utilizes smart contracts for ticket management and token-gating functionality. This provides a secure and transparent way to manage digital assets and access rights. + +- **External Integrations**: Includes a Shopify app (separate project: shopify-gates) for creating token-gating campaigns on merchant stores, powered by OF Keys and OF Stamps. This extends the reach of Offline's technology to e-commerce platforms. + + +Offline External Integrations
+ +## Quick Install 1. First you need to install pnpm in your machine `npm install -g pnpm` 2. Install all the dependencies `pnpm install` @@ -21,7 +67,7 @@ 5. Make sure to apply the migrations to the prisma db and client once the container is running `pnpm prisma-db:dev:start` -## Project structure +## Project Structure **View in [NX Graph](https://sebpalluel.github.io/offline/?groupByFolder=true&select=all)** @@ -37,55 +83,10 @@ The console is used as a backoffice to handle the graphQL server and to innerlin This is the main web app client used to access the whole array of services. -- **Prisma Studio**: `pnpm prisma studio` - -The prisma studio is used to offer an admin interface to the database used by the Nestjs Server app. - - [**Mailhog**](http://localhost:8025/) This is the mail-catcher where all the mail are going in dev environment. -| **Apps and Libs** | **Description** | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `apps/web` | A Next.js app | -| `apps/web/playwright` | Playwright e2e test for the web app | -| `apps/nestjs-server` | A Nest.js server app used to extend Hasura functionalities | -| `hasura` | Contains the config / metadata / migrations / seeds for the Hasura service | -| `prisma` | Prisma database schema and migrations | -| `tools` | Set of tools to be used for DX (Developer Experience) and testing purposes | -| `libs/logger` | Isomorphic logger (a small wrapper around console.log) | -| `libs/utils` | Common utils functions and types for the whole project | -| `libs/workspace` | Contains all the generators and tooling dedicated to maintaining the NX workspace | -| `libs/dlt/types` | Contains the TypeScript types/interfaces related to the DLT (Blockchain) used in the project | -| `libs/next/zustand` | Middleware and util code for Zustand stores | -| `libs/next/biconomy/scw` | Biconomy Smart Contract Wallet library. This contains the logic to set up the Biconomy Smart Contract Wallet with login and logout functions | -| `libs/next/biconomy/store` | Biconomy Smart Contract Wallet store. A Zustand store to handle the state of the Biconomy Smart Contract Wallet | -| `libs/next/gql/[user, admin]` | A library containing all the GraphQL queries and mutations and the generated schemas to be used on the web app. It is divided into 3 folders: `user`, `admin` and `anonymous`, depending on the role of the user | -| `libs/next/gql/thegraph` | A library that uses [The Graph](https://thegraph.com/en/) protocol in order to query data directly from smart contracts on the blockchain | -| `libs/next/hasura/fetcher` | Fetcher functions to query the Hasura service | -| `libs/next/hasura/utils` | Utilities to interact with Hasura | -| `libs/next/siwe/provider` | Next-auth credentials provider for SIWE | -| `libs/next/next-auth/options` | Contains all the configs for [Next-Auth](https://next-auth.js.org/) | -| `libs/next/next-auth/common` | Common functions used in the context of Next-Auth | -| `libs/ui/components` | React reusable components library | -| `libs/ui/shared` | Functions and assets shared in the context of the UI library | -| `libs/ui/theme` | Contains all the specifications for the global style and component style | -| `libs/test-utils/db` | All the utilities relating to the handling of db operations in the context of testing, for example: seeding/deleting | -| `libs/test-utils/functions` | All the utility functions common to every test runner | -| `libs/test-utils/gql` | Offers an SDK and different test account clients to be used on tests in order to interact with the Hasura service | -| `libs/server/api` | API service to query external services (for example: CoinGecko API) | -| `libs/server/alchemy` | Low-level service to interact with the Alchemy RPC provider | -| `libs/server/arbitrum` | Service to interact with the Arbitrum RPC provider | -| `libs/server/ethereum` | Service to interact with the Ethereum RPC provider | -| `libs/server/polygon` | Service to interact with the Polygon RPC provider | -| `libs/server/ethers` | High-level service to interact with EVM compatible blockchains | -| `libs/server/common` | Common functions used in the context of the server | -| `libs/server/cryptocurrencies` | High-level service to get data related to cryptocurrencies: price, market cap, etc. | -| `libs/server/prisma` | Low-level service to interact with the Prisma database | -| `libs/server/task` | High-level service for task scheduling, cron jobs, etc. | - -Each package/app is 100% [TypeScript](https://www.typescriptlang.org/). - # The Stack ## Docker @@ -124,32 +125,6 @@ The command to run all the containers for unit and integration test is pnpm docker:test ``` -## Next.js - - - -The web app is using [next.js meta-framework](https://nextjs.org/) v13 in order to leverage serverless api functions and react hybrid SSR/SSG/PWA capabilities. The web app is using the [next-auth](https://next-auth.js.org/) library to handle the authentication and the authorization and the ChakraUI components library. - -## Hasura - - - -The [Hasura service](https://hasura.io/) is used as a GraphQL API gateway to the Postgres database and for introspection into the prisma database. It is also used to handle the authentication and authorization of the users through a Next-Auth adapter. - -It act as the single endpoint for the web app to query the database and the external services like the Nestjs Server app in a federated way. - -## Prisma ORM - - - -The [Prisma ORM](https://www.prisma.io/) is used in the context of the Nest.js Server app to interact with the prisma Postgres database. It is used to generate the database schema and the migrations and offer an admin with [Prisma Studio](https://www.prisma.io/studio). - -## Nest.js - - - -The [Nest.js](https://nestjs.com/) framework is used to extend the Hasura functionalities. It serves as a complementary layer to Hasura to handle the business logic of the application and to interact with the external services like the blockchain and the crypto APIs. Currently it serves as a service to handle the retrieval of the user's wallet balance of ERC20 tokens on the Ethereum/Polygon/Arbitrum blockchains. More info in the [Nest.js Server app README](./apps/nestjs-server/README.md). - ## Storybook @@ -172,13 +147,6 @@ This repo has some additional tools already setup for you: - [Playwright](https://playwright.dev) test runner for E2E and components test - [Graphql Code Generator](https://www.the-guild.dev/graphql/codegen/) a generator for the graphql schemas and a client builders with provided queries. -## Flavors - -Looking for a specific feature ? We have a few flavors 🍦 to choose from: - -- [with_waltid_idpkit](/sebpalluel/offline/tree/with_waltid_idpkit): a flavor that uses the [WaltID IDPKit](https://walt.id/idp-kit) to provide sign-in in with a DID. -- [with_web2_signin](/sebpalluel/offline/tree/with_web2_signin): a flavor that uses the common Web2 sign-in methods such as OAuth or Email/Password. - ## Libraries ### Next Auth @@ -193,24 +161,6 @@ You can find the different providers used by next-auth in `libs/next/next-auth/o Hasura is used as an adapter to next-auth in order to persist in a database the user's provided information such as their `id`. The adapter is located in `libs/next/hasura/adapter`. - - -### Rainbowkit - -### Biconomy - - - -This project leverages the capabilities of [Biconomy](https://www.biconomy.io/), a blockchain middleware platform that simplifies the user experience of your web3 service by offering features such as gasless transactions and smart contract wallets. With Biconomy, users can interact with dApps without worrying about the complexity of the underlying blockchain network. - -To streamline the authentication process, Biconomy integrates with the Web3Auth protocol, providing a standardized way for users to authenticate themselves to dApps using their Ethereum wallets. Additionally, Biconomy's middleware layer can be used to simplify the integration of Web3Auth into dApps, allowing for secure and reliable access to Web3 wallets. - -While Biconomy itself does not offer a Social Login feature, Web3Auth supports this functionality by allowing users to authenticate themselves using their preferred social media accounts, such as Google or Facebook, in addition to their Ethereum wallets. For more information about Web3Auth, please visit the [Web3Auth website](https://web3auth.io/). - - - - - ### GraphQL code generator @@ -229,18 +179,6 @@ The graphql queries definition are defined in `libs/gql/user/api/queries`. We us The graphql queries definition are defined in `libs/gql/admin/api/queries`. We use a generic sdk with a simple fetch query in order to facilitate the querying the data for the admin role. Those queries are made on the server side of the frontend. Hasura will allow the request through the providing of the `X-Hasura-Admin-Secret`. -### The Graph: Graph Client - - - -The [Graph Client library](https://github.com/graphprotocol/graph-client) is used in order to interact easily with any smart contract on blockchain supported by [The Graph protocol](https://thegraph.com/en/). - -The library located in `libs/next/gql/thegraph` integrate the client and the toolset from The Graph in order to generate the graphql code to be used by the web app to fetch live data from desired smart contracts. - -The query are defined in `libs/next/gql/thegraph/queries` and the smart contract sources are defined in `libs/next/gql/thegraph/src/.graphclientrc.yml`. When updating queries or smart contract sources, be sure to launch the command `pnpm thegraph-build` in order to generate the new version of the generated files located in `libs/next/gql/thegraph/.graphclient`. - -You can find an example of live query of smart contract on the [Blockchain page](http://localhost:8888/en/blockchain). - ## Test ### Jest @@ -272,10 +210,6 @@ Coverage for all the libraries is created in the root of the workspace. In order } ``` -To facilitate integration testing, you have access to 3 clients with corresponding users: `Alpha Admin`, `Beta Admin`, and `Seb Google`. These clients, located in the `test-utils-gql` library, offer GraphQL instances with all the available queries for a user. - -You can check the tests in `users.spec.ts` and `adapter.spec.ts` for examples of these utilities in use. - ### Playwright @@ -293,7 +227,7 @@ The test command will wait for all the necessary services to be reachable before To run all the Playwright tests on affected code, you can use the command: ```shell -pnpm affected:web:e2e +pnpm affected:e2e ``` ## NX @@ -310,7 +244,7 @@ In a workspace, libraries are typically divided into four different types: #### Feature -Libraries that implement “smart” UI (e.g. is effectful, is connected to data sources, handles routing, etc.) for specific business use cases. +Libraries that implement "smart" UI (e.g. is effectful, is connected to data sources, handles routing, etc.) for specific business use cases. #### UI @@ -324,176 +258,192 @@ Libraries that contain the means for interacting with external data services; ex Libraries that contain common utilities that are shared by many projects. -### Adding capabilities to your workspace +## Configure the project with your own `.local.env` API keys (mandatory) -Nx supports many plugins which add capabilities for developing different types of applications and different tools. + -These capabilities include generating applications, libraries, etc as well as the devtools to test, and build projects as well. +**In order to run the project, you need to configure the following environment variables in you `.local.env` file:** -Below are our core plugins: +### Alchemy -- [React](https://reactjs.org) -- `npm install --save-dev @nx/react` -- Web (no framework frontends) -- `npm install --save-dev @nx/web` -- [Node](https://nodejs.org) -- `npm install --save-dev @nx/node` +The Nestjs and Nextjs Apps uses [Alchemy](https://alchemy.com/?r=ba8fc42476de40ad) as an RPC provider for the Ethereum, Polygon and Arbitrum blockchains. You need to create an account and [get an API key for those on the alchemy dashboard](https://dashboard.alchemyapi.io/?r=ba8fc42476de40ad): -There are also many [community plugins](https://nx.dev/community) you could add. +```bash +ALCHEMY_ETHEREUM_MAINNET_TOKEN= +ALCHEMY_POLYGON_MAINNET_TOKEN= +ALCHEMY_ARBITRUM_MAINNET_TOKEN= +# Warning ! Those api keys are going to get leaked in the client side code so it's advised to set ALLOWLIST DOMAIN in the alchemy dashboard to your apex domain (in our case www.offline.app) in order to avoid someone hijacking your api keys. By default a public rpc network is used for the client side code so you don't need to set those api keys if you don't want to. +# NEXT_APP_ALCHEMY_ETHEREUM_MAINNET_TOKEN= +# NEXT_APP_ALCHEMY_POLYGON_MAINNET_TOKEN= +# NEXT_APP_ALCHEMY_ARBITRUM_MAINNET_TOKEN= +``` -### Generate an application +### JWT secret keys -Run `nx g @nx/react:app my-app` to generate an application. +In order to secure your JWT authentication provided by [Next Auth](https://next-auth.js.org/) you are going to need to generate your own RSA-256 keys. -> You can use any of the plugins above to generate applications as well. +### Configure Hasura and Next Auth with same RSA key -When using Nx, you can create multiple applications and libraries in the same workspace. +You need to configure hasura and next auth to have the same asymmetric key. One is provided by default but you can generate your own RSA 256 key using those commands: -### Generate a library +```shell +# Don't add passphrase -Run `nx g @nx/react:lib my-lib` to generate a library. +ssh-keygen -t rsa -P "" -b 4096 -m PEM -f jwtRS256.key -> You can also use any of the plugins above to generate libraries as well. +ssh-keygen -e -m PEM -f jwtRS256.key > jwtRS256.key.pub +``` -Libraries are shareable across libraries and applications. They can be imported from `@workspace/mylib`. +