HCB is a tool for hackers to hack on the real world, like GitHub, but for building with atoms and people, not bits and cycles. Thank you so much for contributing to the HCB database.
Let's get the HCB codebase set up on your computer! We have setup a easy and simple guide for you to get it running on your computer!
We've been building HCB since 2018, navigating the codebase can be difficult at times. The codebase generally follows the Model-View-Controller design pattern, which Ruby on Rails is built around. If you need help, reach out to us in #hcb-dev. "Getting Started with Rails" is a comprehensive guide for first-time Rails developers.
Every project on HCB is considered an "organization" (the model for them is named Event, however). Users can be members of multiple organizations. OrganizerPosition acts as a many-to-many join table between Event and User. OrganizerPositionInvite is a "pending" connection between the two, we create an OrganizerPosition after the user accepts the invite.
Most financial transactions take place using our two bank accounts with Column. We also have bank accounts with Silicon Valley Bank (funny story!) and TD Bank.
We use Stripe to enable invoice sending (Stripe Invoicing), accept payments / donations (Stripe Payments), and issue physical and virtual cards (Stripe Issuing).
Column is used to send checks, accept check deposits, send ACH transfers, generate an organization's account / routing number and create book transfers (these represent internal transfers). Refer to Column's documentation for more information.
PayPal transfers are sent manually by HCB's operations staff.
Disbursements are internal transfers from one organization to another. These are sometimes called “HCB transfers” in the interface.
Reimbursements are internal transfers to a "clearinghouse" organization on HCB which then sends an external transfer via ACH, check etc.
In the past, we've used Increase, Emburse and Lob. We've also relied heavily on Plaid, however, we use it less nowadays.
Card transactions as well as ACHs, reimbursements, checks, and PayPal transfers require receipts. Models that allow adding receipts include the Receiptable concern. Receipt Bin is a tool created to manage "unlinked" receipts that haven't been paired to transactions, these receipts have their receiptable_id set to nil.
We collect fees on all revenue collected by organizations, typically 7%. This process is handled by a set of cron jobs and we make book transfers on our Column account to represent money moving from an organization's account to our operating fund.
The transaction engine is the core of HCB's codebase. It's role is to map transactions that happen in on our underlying bank accounts to their associated organization. Almost every action a user takes on HCB will go through the transaction engine at some point.
Our transaction engine is summarised in @sampoder's talk at the SF Bay Area Ruby Meetup: How we built a bank w/ Ruby on Rails.
Canonical pending transactions are transactions we expect to take place but they haven't occurred yet in our underlying bank account. For example, we create a canonical pending transaction the moment you send an ACH transfer even though the transfer only gets sent via Column once a operations staff member has approved.
Canonical pending transactions appear on the ledger as "PENDING:" until a canonical transaction is made.
Canonical transactions represent transactions that occur on our underlying bank account / show up on our bank statement. Our accountants and auditors rely on each transaction (including internal transfers) appearing on our bank statements.
These models map canonical pending transactions and canonical transactions to their associated event.
A canonical pending settled mapping is created to match canonical pending transactions with canonical transactions when a transaction settles.
HCB codes group together canonical transactions and canonical pending transactions into transactions we can display on the ledger. For example, a donation has a canonical transaction for both the money paid through the card and a refund for the Stripe processing fee. When we display a transactions, we display the HCB code.
Raw transactions, for example RawStripeTransaction or RawColumnTransaction, represent the information we receive from external services such as Stripe or Column about transactions made through them.
For more extensive documentation on HCB's transaction engine, I recommend reading the guides linked above.
HCB's operations team perform their work through the admin dashboard on HCB and an Airtable base. Financial operations take place on the admin dashboard. Meanwhile, promotions (eg. free 1Password) and applications (collected via hackclub/site) are managed through the Airtable.
HCB is deployed on Heroku. We have two dynos, one for Rails and one for our Sidekiq workers. We handle errors using Airbrake and AppSignal. We also run status.hackclub.com using Checkly.
