#### Notice This article has been written with explicit permission from my then employer, and good friend Premodial Zhou. ### Intro My friend Premo contacted me out of the blue at the tail end of last year and said he has this project he needs someone to work on. A MVP for a platform on which commodities can be bought and sold in bulk. I was not fully convinced, but he then said I can use whatever I want. I said I wanted to use Remix, after making a case for it he said yes. I was happy, he was happy and the project got going. I never used Remix before, but I heard it works great for websites similar to this, so I took a gamble and challenged myself to learn it from scratch. What made choosing Remix possible was that I was to be the sole developer working on the project, except for the guy that did the Figma design. The project had to be done in 4 months and I was asked to provide deliverables each week. Which was quite a tall order considering all the requirements and some more that only became evident at about the half way mark that resulted in a bunch of reworks. By the end I managed to completed the project in 4 and a half months, regrettably with a few rough edges here and there but it worked well enough and can be used as a future basis. I am proud of what I accomplished minus one or two halve baked features. But I can comfortably say that the project and the time constraints imposed on it improved my development capabilities by a great extent, especially hearing feedback, which I now see as an invaluable resource. ### Using the system Description

Starting at the beginning, the app supports both credentials and identity provider accounts with the possibility to add any number of additional account providers with the way tables are set up in the DB. Each provider would have their own table that would be joined on a master table holding the account's internal ID. For the credentials account, the usual checks are done on the client to provide feedback as they type, i.e., password strength, and if passwords match. On the server additional and overlapping checks are done as to filter user input and to make sure what the server receives is what is expected. This is accomplished primarily by using Zod, it was used extensively on the server. The user may be provided feedback in the form of a toast on some occasions, like if an account with the given email already exists. Description

This is what the user sees after their first login. On the left is the menu, which allows users to visit various portals. On the right is the market, listing all the available commodities for sale at the moment. At this point, the user has two actions to take, as seen in the "Start your journey" banner: identity verification and creating or joining an organization. The user's freedom is not completely limited before completing these steps. They can still view commodities, create or join an organisation, or start creating commodities for listing once their organisation is verified. This approach allows users or companies to explore what the system offers and encourages them to invest their time in it without being locked out of the system while waiting for admin approval to proceed to the next step. Every page has a relevant notice informing the user what needs to be done or what has to be verified by an admin for the page's functionality to fully unlock or commodities to become public. Description

The first step, identity verification. The user must provide some basic information as well as upload their ID and a image of their face to be matched with their ID. After submission the user is able to make changes and reupload documents. This is pared with a nice loading spinner indicating that a submission is in progress. Once the user submitted everything that's required they will be notified that an admin task has been created to review their submissions. Each submission can have one of 4 states; awaiting submission, submitted, accepted or rejected. The accepted and rejected states are set by the admin upon review. This us what the admin sees in the admin portal: Description

First, under user accounts, they can see that an account requires their attention. And on clicking it: Description

Which in the case of this image is after they have already reviewed and accepted everything. If everything is accepted, the account automatically takes on the "Verified" state. If the admin rejects a submission the admin task is cancelled and the user has the opportunity to resubmit the rejected submission. Each submission can be accepted or rejected in isolation. Once a user has been verified they can create or join an organisation. Originally the admin had a text box under each submission to specify a rejection reason if necessary, this message would then appear in the users identify verification page. But due to complexity this was disabled to be reactivated late which did not happen as the deadline loomed and other features were deemed more important. It was a very clear, easy and efficient way to deliver feedback to the user, and was envisioned to be used throughout the app. Back in user land: Description

The user can clearly see that each of their submissions have been accepted or rejected and if they have successfully been verified or not. Next up, the user can create or join an organisation. We will be creating one: Description

If an organisation with the same name already exists, the user receives an error toast. Description

Once created the user is prompted to select the newly created organisation, as to "enter" it. The app allows users to be part of many organisations and they can switch between them at will. One company might run two mines but would like to keep them organizationally apart but have some common people. Once selected the "Select organisation" text at the top left changes to reflect the name of the current active org. The user now has the ability to trade, acting as the selected organisation. That is, if the organisation goes through a similar verification process as a user account. An organisation can be verified either as a buyer, or supplier. Or both. The only difference is that the documents needed are different. Common documents to both roles are automatically shared and no resubmission is required if they have already been verified in either role. Description

Above is the organisation's inventory page. From here they can create inventory by selecting a commodity type from the dropdown, as well as editing a plethora of options within each commodity once created. Currently the selected organisation has not been fully verified, but this does not limited users from creating and editing commodities. The only property unverified suppliers cannot change is the market visibility of if their commodities, which is locked to private until the org is verified. This allows organisations to fill out their inventory while admins are verifying their documents. Once verified, their commodities can be made public immediately.

This is the commodity configuration page. Up to the organisation can specify their internal name for the commodity. Say for instance they have 2 different grades if chrome and they want to distinguish between them. Additionally they can specify the price per tonne, a public facing description and a PDF document that can be used to describe the commodity's exactly properties like purity. Each mine has a different way of doing it, and it depends on what time of commodity they are selling. Next, they can specify their available capacity of their commodity using a graph:

They can adjust the view period as needed to see past, present or potentially future capacity if set. In the picture, the red line represents new capacity, i.e. Changes to capacity that has not been saved yet. The blue line indicates set capacity, which defaults to 0 tonnes per month. After "Set Capacity" is clicked the blue line will adjust to take on the form of the red line. This set capacity can then be seen publicly, indicating to any potentially buyer what tonnage is available to buy each month. After a sale the supplier adjusts the graph to reflect the change in available capacity. It was decided not to do this automatically at first due to potentially overlooked factors as supply and consumption can be a tricky thing, especially in the case of mines. Storage is one such potential factor. Description

Commodities may be archived if not longer being sold. The commodity is still retained in the database to allow for current orders to be completed and to enable the viewing of past orders. The commodity will be removed from the active commodities and its visibility will become private once more. After the organisation has been verified the commodity can be made visible on the market for buyers to purchase. I am not going to show the organisation verification process as it is similar to the account verification process, only with different documents. The organisation should additionally provide an email and if they are registering as a supplier, their bank details as well. Description

Here the new chrome commodity is visible on the market, available to be bought. If a buyer wants to purchase the commodity they are required to create an organisation and register as a buyer. Again, the process is very similar so I wont show it again. ### Buying process The buying process requires the cooperation of all three parties involved, the buyer, supplier and broker. Firstly, the buyer places an order by opening the commodity they are interested in and specifying the desired quantity of the commodity in each month for the duration of the order. Then, after clicking "Order" the order is placed and sent of to the supplier. The supplier can then see what quantities the buyer requested in each specified month. The supplier can then make a choice as to accept or reject the order, after which the buyer is informed. If accepted, the buyer will be informed, and is then required to make the payment in full into the broker's bank account. On the broker's side; the admin portal, they can confirm that they received the payment from the buyer which is then visible to both the buyer and supplier. After which the broker takes their cut of the payment and pays the rest into the supplier's bank account. Lastly, the supplier can confirm they received the payment and the order can commence. Each step in the ordering process is visible to all parties so everyone knows in what state the order is at all times and who is responsible for the next step. Description

Here, the buyer proceeds to specify the monthly required quantities and places the order. Once places the order is listed under "Orders" in the buyer portal from where the buyer can keep track of it: Description

The responsibility now falls on the supplier to either accept or rejected the order. From the supplier's point of view: Description

After accepting both the broker and buyer can see the state change and that the next responsibility falls on the buyer to make the payment into the broker's bank account. POV from the broker: Description

And finally from the point of view if the supplier once they received payment from the broker: Description

Now the buyer and supplier plays ping pong as the brokers/admins oversee the order and organizes transport: Description

Once the order is completed the admins can mark it as such after which it is moved to "past orders" for all three parties. ### Shortcomings The biggest shortcoming would definitely be the payment system. The app does not integrate any payment gateway but rather relies on bank transactions to move money around which is not ideal as it introduces unnecessary steps and increases the potential for error. We discussed using a payment gateway like Payfast which supports split payments, meaning that the buyer pays the supplier directly and a cut of that payment is automatically split of and given to the broker. That alone would cut out about 3 back and forth steps. The reason we did not go with Payfast was if I remember correctly is that Payfast takes quite a considerable cut for themselves and additionally, this only being a minimum viable product that was intended for feasibility testing. Apart from that, I would have liked to clean up the order and payment systems. They are visually not very appealing and possibly confusing, unfortunately the deadline creeped closer and closer so sacrifices had to be made. ### Tech Stack The app was built using Remix 2.6, which was the first version that introduced unstable Vite support, moving away from the purpose built Remix compiler. It was a challenge to host the app as hosting providers like Vercel and Netlify did not support the Vite configuration yet, but eventually I got it to work flawlessly on Fly.io with zero encountered stability issues. Choosing Remix turned out to pay dividends at the end as Remix's nested routing and loader->component->action data flow was absolutely perfect for this use case. Additionally Remix has fantastic hooks like useFetcher that makes it trivial to add loading spinners and busy states in addition to updating the UI. It was a amazing experience all round even though this was my first project using Remix, jumping ship from Next. Postgres was used as the DB in conjunction with postgREST that turns the DB into a restful API. It was quite a struggle to get this setup to work at first but I am glad I stuck to it. The first I heard of postgREST was that Supabase uses it behind the scenes so I wanted to know more about it and how it works and why someone would want to use it. Turns out it provides an excellent developer experience once set up, making it trivial to query the DB and execute procedures. I would absolutely positively recommend using postgREST in front of Postgres. It replaces the need for a ORM in most cases per my experience. Some other notable libraries or services: AWS S3 was used for to store documents and images. React Aria was used for the UI which was a mostly positive experience. Tailwind was used for styling. PDFKit for generating invoices Sonner for toasts immer for easier state changes And lastly Zod for schema declarations and validation which turned out to be an irreplaceable tool.

Reghardt's Blog

Commodity trading platform MVP - Alomi Minerals