{"id":13425737,"url":"https://github.com/deptagency/algomart","last_synced_at":"2025-04-09T09:07:45.839Z","repository":{"id":37106260,"uuid":"421431773","full_name":"deptagency/algomart","owner":"deptagency","description":"Algorand NFT Storefront platform","archived":false,"fork":false,"pushed_at":"2023-03-06T16:29:13.000Z","size":36533,"stargazers_count":180,"open_issues_count":108,"forks_count":77,"subscribers_count":22,"default_branch":"main","last_synced_at":"2024-04-14T13:42:38.788Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://demo.algomart.dev/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deptagency.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-10-26T13:16:09.000Z","updated_at":"2024-03-21T23:01:36.000Z","dependencies_parsed_at":"2024-01-03T05:17:36.488Z","dependency_job_id":"a134f876-18dd-4e2e-bde1-87cb19e85c82","html_url":"https://github.com/deptagency/algomart","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deptagency%2Falgomart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deptagency%2Falgomart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deptagency%2Falgomart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deptagency%2Falgomart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deptagency","download_url":"https://codeload.github.com/deptagency/algomart/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248008630,"owners_count":21032556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T00:01:17.680Z","updated_at":"2025-04-09T09:07:45.818Z","avatar_url":"https://github.com/deptagency.png","language":"TypeScript","funding_links":[],"categories":["Application Platforms \u0026 Examples","Developer Resources","NFT Marketplaces"],"sub_categories":["NFT Marketplaces","Open-source Projects and Code Examples","Projects"],"readme":"\u003cbr /\u003e\n\u003cp align=\"center\"\u003e\u003cimg alt=\"AlgoMart Logo\" src=\"./AlgoMart-Logo.png\" width=\"400\" height=\"140\"\u003e\u003c/p\u003e\n\u003cbr /\u003e\n\n# AlgoMart Marketplace\n\n## 🚧 2.0 Work In Progress 🚧\n\n### Please note that the current version of this project should be considered _*unstable*_ for the time being as we finalize the upgrade to version 2.0\n\n---\n\n[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)][code of conduct]\n\n### Migration\n\nThis project is developed to be a foundational starter for creating your own NFT storefront on the Algorand blockchain. It is a monorepo that includes:\n\n- A [headless CMS](./apps/cms) (Directus)\n- A [back-end API](./apps/api) (Fastify)\n- A [job server](./apps/scribe) (BullMQ)\n- A [front-end](./apps/web) sample implementation (NextJS)\n- Shared [libs](#libs)\n- [Terraform templates](./terraform/envs/dev) for setting up infrastructure on Google Cloud Platform\n- [GitHub Workflows](./.github/workflows) for linting, type-checking, building, dockerizing, and deploying\n\n## 📚 General Project Overview\n\nThe main purpose of this platform is twofold; to make it easy for developers to spin up a custom storefront that interfaces with the blockchain, and to make that storefront accessible to the storefront administrators and its end-users who might not be familiar with the technical nuances of blockchain technology.\n\nIn order to accomplish this, storefront administrators should be able to easily to create, configure, and mint NFTs. Likewise, end-users should be able to redeem, purchase, or bid on them without concern of what's happening behind the scenes on the blockchain.\n\n### Backend Overview\n\nTo accomplish these challenges, **templates** are used within the CMS.\n\nNFT Templates represent an NFT that will be minted (any number of specified times). It includes key information such as title, description, rarity, and other important configurable metadata that will be consumed by the API.\n\nNFT Templates are grouped within Pack Templates. Packs can contain one or more NFT Templates and also have a number of configurable settings. Most notably, they can be set to be purchasable, to be auctioned, to be claimed via an auto-generated redemption code, or to be given away free. For a full overview of the CMS model, see the [CMS README](apps/cms/README.md).\n\nMeanwhile, the API continually polls the CMS for new NFT Templates and Pack Templates. So once the templates are configured in the CMS, the API will find them, generate the NFT instances in the API's database, and then group them into Packs based on the Pack template's configuration.\n\nFrom here on out, the NFT and Pack information can be accessed from the API and displayed to an end-user, who can then purchase, bid on, redeem, or freely claim the Pack (based on the corresponding Pack template's configuration).\n\n### Frontend Overview\n\nThe backend API can be accessed via REST endpoints by a frontend. This frontend can be custom-built, or the included NextJS web project can be used and further customized.\n\nWhen an end-user registers through the site, a user account record is created via the API and a new Algorand wallet is generated on their behalf. That wallet's mnemonic key is encrypted via a secret PIN code the end-user provides upon sign-up.\n\nAn authenticated end-user can then engage in user flows that allow them to acquire Packs (again, containing one or more to-be-minted NFTs). In the case of a monetary transaction, an end-user can enter their credit card information. Upon submission, this information will be validated and processed via Circle's Payments API. Upon a valid confirmation, the API then mints and transfers the assets to the user's wallet.\n\n## 🚧 Pre-release\n\nThis software is in a pre-release state. This means while we strive to keep it stable and include database migrations, sometimes we may introduce breaking changes or an accidental bug. Follow our [issue tracker][issue tracker] for more details on what's coming next.\n\n## ✅ Requirements\n\n- Node.js v16.10 or greater (lts is v16.13.1 as of Jan 2022 and works well), npm v7 or greater (manage version via [nvm][nvm])\n- PostgreSQL ([Postgres.app][postgres app] is recommended on macOS, or run via `docker-compose up db`)\n- [Redis][redis] for jobs\n- algod (Algorand node)\n  - Consider using a [third party api][third party api] for initial setup and experimentation.\n  - A [sandbox][sandbox] is [recommended][recommended] for continued learning about Algorand and its smart signatures/smart contracts\n- [Circle][circle] account for taking payments\n- [Firebase][firebase] account for authentication\n- [Pinata][pinata] account for storing NFTs\n- [Chainalysis][chainalysis] for blockchain address verification\n\n## 🤷 Optional\n\n- [SendGrid][sendgrid] for sending email notifications\n- [Google Cloud Platform][gcp] account for hosting\n- Install the [Nx CLI][nx cli] for ease of development: `npm i -g nx`\n- [Docker][docker] for a local dev environment using VSCode Dev Containers or docker compose\n\n## 🚀 Get Started\n\nYou can either build and run each application manually or you can use `docker-compose`.\n\n### Development Environment Setup\n\n1. Create .env files\n\n   ```bash\n      cp ./.env.exmaple ./.env\n      cp ./apps/cms/.env.example ./apps/cms/.env\n      cp ./apps/scribe/.env.example ./apps/scribe/.env\n      cp ./apps/api/.env.example ./apps/api/.env\n      cp ./apps/web/.env.example ./apps/web/.env\n   ```\n\n2. Address ` SETUP:` comments in env files\n\n3. Initialize the databases with `npm run drop-tables \u0026\u0026 npm run initialize`\n\n4. Start the CMS `nx serve cms`\n\n   1. If database is empty, it will automatically seed itself with test data\n   2. Checkpoint: you should be able to log in the CMS and see some sample pack templates (http://localhost:8055/admin/content/pack_templates)\n\n5. Start the job server `nx serve scribe`\n\n   1. Checkpoint: you should be able to see the jobs dashboard (http://localhost:3002/bullboard)\n   2. Run the `sync-cms-cache` job manually, twice, by promoting the delayed job in the dashboard\n   3. Checkpoint: you should see rows in the Pack table in the API database (`algomart_api.public.Pack`)\n\n6. Start the API `nx serve api`\n\n   1. Checkpoint: you should be able to see swagger docs (http://localhost:3001/docs/static/index.html)\n\n7. Start the web server `nx serve web`\n\n   1. Checkpoint: You should be able to register an AlgoMart account, sign in and see some drops available (http://localhost:3000/drops)\n\n8. Configure [Circle webhooks](apps/api#circle-webhooks)\n\n   1. Add Money to your merchant wallet to cover/float [pending end user credit card transactions](https://developers.circle.com/docs/post-payments-processing#card-payments-settlement)\n      1. Get your merchant wallet's address using your Circle my-sandbox account's \"Transfer from a blockchain wallet\" functionality\n      2. Send testnet USDC to your merchant wallet from [Algorand Testnet Dispenser](https://dispenser.testnet.aws.algodev.network/)\n   2. Checkpoint: you can add money to your wallet using one of Circle's [test card numbers](https://developers.circle.com/docs/test-card-numbers)\n\n9. Purchase a pack using credits\n\n   1. Using credits from the previous step\n   2. Checkpoint: you have collectibles in your collection\n\n10. Configure an Algorand sandbox (optional)\n\n    ### Local Algorand Setup\n\n    This is an alternative to using a 3rd party Algorand node API.\n    For local development, the [Algorand Sandbox](https://github.com/algorand/sandbox) is handy docker instance that makes interfacing with the blockchain simple from your local machine.\n    More information on Sandbox vs Third-party API services [here](https://developer.algorand.org/docs/get-started/devenv/)\n\n    - Download the [Algorand Sandbox](https://github.com/algorand/sandbox) and start up the docker instance:\n\n    ```bash\n    ./sandbox up\n    ```\n\n    - By default this will create a private network, as well as fund a few accounts with Algos. You'll need to generate a passphrase mnemonic for one of these accounts. To see the list of the created accounts:\n\n    ```bash\n    ./sandbox goal account list\n    ```\n\n    - Take the `\u003cADDRESS\u003e` from the first account and input here\n\n    ```bash\n    ./sandbox goal account export -a \u003cADDRESS\u003e\n    ```\n\n    Use this outputted mnemonic as the FUNDING_MNEMONIC variable within the `.env` file within the `api` and `scribe` projects.\n\n    _Disclaimer:_ If you use a private network as described above, you will not be able to test features that require a public network, including the [Pera Wallet](https://perawallet.app/) (the mobile non-custodial wallet app for Algorand). For running a public network node, see below.\n\n    ### Testnet Algorand Setup\n\n    Alternatively you may choose to run the algorand sandbox on a public network such as testnet. In that case you'll need a few additional steps, such as creating and funding an account.\n\n    - To run sandbox on testnet:\n\n    ```bash\n    ./sandbox up testnet\n    ```\n\n    - Then create an account:\n\n    ```bash\n    ./sandbox goal account new\n    ```\n\n    This will create a new, unfunded account. Testnet accounts can be funded with fake Algos using the [Testnet Dispenser](https://dispenser.testnet.aws.algodev.network/). You can then follow the account export steps above to get your mnemonic passphrase.\n\n    _Disclaimer:_ The sandbox testnet configuration will not provide an indexer. There are public indexer's available (e.g. https://algoindexer.testnet.algoexplorerapi.io/), and the Indexer Configuration will need to be updated in both `app` and `scribe` .env files.\n\n    To learn more about available `goal` CLI commands for e.g. creating a new account, see [the Alogrand docs](https://developer.algorand.org/docs/clis/goal/goal/).\n\n## 💾 DB initialization\n\nTo initialize the databases:\n\n```bash\nnpm run drop-tables  # drop existing CMS and API databases\nnpm run initialize   # initialize the CMS and API databases\n```\n\n## 🏃 Run\n\nRun all 4 projects (api, cms, web, \u0026 scribe) simultaneously with combined output.\n\n```bash\nnpm start\n```\n\n## 📦 Build\n\nTo build _everything_:\n\n```bash\nnpm run build\n```\n\n## ⚙️ Unit Tests\n\nTo run all tests:\n\n```\nnpm test\n```\n\nTo run tests/lint only a specific library:\n\n```bash\n# assuming shared-utils is an nx library\n# (ie. an alias for libs/shared/utils defined in workspace.json)...\nnx run shared-utils:test\nnx run shared-utils:lint\n```\n\n## ⚙️ E2E Tests\n\nTo run End-to-end integration tests with Cypress:\n\nBe sure to follow steps outlined in the [web-e2e README](apps/web-e2e/README.md) first.\n\n```bash\n# To open the Cypress UI and watch the tests run:\nnpm run test:cypress:open\n\n# To run the test in the terminal\nnpm run test:cypress:run\n```\n\n## 🧹 Linting\n\nTo run eslint for all projects:\n\n```\nnpm run lint\n```\n\n## 🐳 Running with docker-compose\n\nAlternative to running the services manually, they can also be run via Docker. After creating the relevant `.env` files above, add a file called `.babelrc` to the root of the web project (`apps/web/`) and populate it with:\n\n```json\n{ \"presets\": [\"next/babel\"] }\n```\n\nThen run all services:,\n\n## 🆚 Running with VSCode Dev Containers.\n\nThis codebase leverages VSCode Dev Containers.\n\n1. Install VSCode Remote Containers plugin.\n\n1. Open the project in VSCode. When prompted, click the \"Reopen in Container\" button\n\n## 🪆 Project dependencies\n\nWhen updating dependencies, there are a few things that must be kept in mind.\n\n### Directus\n\nIf doing any updates to the Directus version, the version numbers must match across the application and the snapshot.yml file must be created with the updated version. You can use `apps/cms/scripts/directus-update.sh` to perform these steps. Update the version number at the top of the script.\n\n1. Update versions\n   1. Pin `directus`, `@directus/sdk`, and `@directus/extensions-sdk` versions in `package.json`\n   1. Pin `host` version in `/apps/cms/extensions/displays/pack-price/package.json`\n   1. Pin `host` version in `/apps/cms/extensions/interfaces/price-conversion/package.json`\n   1. Pin `host` version in `/apps/cms/extensions/hooks/import-data/package.json`\n   1. Pin `host` version in `/apps/cms/extensions/hooks/kyc-management/package.json`\n   1. Pin `host` version in `/apps/cms/extensions/hooks/set-verification-status/package.json`\n   1. Set npm install step of `/docker/deploy/cms/Dockerfile` to version\n1. Run `npm install` from root to generate latest `package-lock.json`\n1. Run `nx export cms` to generate latest `snapshot.yml`\n1. Rebuild cms extensions, either via `nx build cms` or all of these:\n   1. Run `nx build-price-display cms` to generate latest js file\n   1. Run `nx build-price-interface cms` to generate latest js file\n   1. Run `nx build-import-data cms` to generate latest js file\n   1. Run `nx build-kyc-management cms` to generate latest js file\n   1. Run `nx build-set-verification-status cms` to generate latest js file\n\n## Libs\n\n`libs/*`\n\nShared Typescript [interfaces and enums](./libs/schemas)\n\nFor performance and code organization reasons, the [Nx docs](https://nx.dev/structure/applications-and-libraries) recommend\nputting as much functionality as possible into libs, even if the code is only used in a single app. In Nx, a lib is more than just a directory under the `libs/` directory. Each lib must have an entry in the workspace.json file for the lib to build and import correctly.\n\nLinting will fail for any lib code that tries to import code from an app. This means that lib code should never access things like\nglobal configuration variables or environment variables. (eg. `Configuration`) Rather, lib code should receive any environment configuration via\narguments that are passed in.\n\nIf you wanted to create a new library at the path `libs/shared/utils`, you'd use the nx generator...\n`nx generate @nrwl/node:lib utils --directory shared`\n\n## 🚢 Deployment\n\nPlease see the detailed [step-by-step guide](./docs/deploy/README.md)\nfor instructions on how to use the included Terraform templates\nand Github Workflow to create a complete storefront environment\non Google Cloud Platform.\n\n[algorand sandbox]: https://github.com/algorand/sandbox\n[api]: apps/api\n[circle]: https://www.circle.com\n[cms]: apps/cms\n[code of conduct]: CODE_OF_CONDUCT.md\n[directus]: https://directus.io\n[firebase]: https://firebase.google.com/\n[gcp]: https://cloud.google.com\n[issue tracker]: https://github.com/deptagency/algomart/issues\n[nvm]: https://github.com/nvm-sh/nvm\n[postgres app]: https://postgresapp.com\n[schemas]: libs/schemas\n[sendgrid]: https://sendgrid.com\n[web]: apps/web\n[nx cli]: https://nx.dev/using-nx/nx-cli#nx-cli\n[pinata]: https://www.pinata.cloud/\n[scribe]: apps/scribe\n[redis]: https://redis.io\n[docker]: https://www.docker.com\n[third party api]: https://developer.algorand.org/docs/get-started/devenv/#2-third-party-api-services\n[sandbox]: https://developer.algorand.org/docs/get-started/devenv/#1-sandbox\n[recommended]: https://developer.algorand.org/docs/get-started/devenv/#recommendation\n[chainalysis]: https://www.chainalysis.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeptagency%2Falgomart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeptagency%2Falgomart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeptagency%2Falgomart/lists"}