SudoSOS Back-end API v0.1.0 ​
Modules ​
| Module | Description |
|---|---|
| authentication | Authentication within SudoSOS is based around JWT tokens. However, there are many ways to retrieve a JWT token, and the token itself is not stored in SudoSOS. Instead, the token is stored in the user's browser, and is sent with every request to SudoSOS. |
| balance | A user's balance is the net of every transaction and Transfer on their account. Positive means SudoSOS owes them; negative means they owe SudoSOS and need to top up. |
| banners | banners are used to manage promotional material within SudoSOS, commonly displayed on the point of sale. They can be configured with a duration, activation status, and start/end dates to control their visibility. |
| catalogue/containers | A container is a group of products of a single seller, offered together at one or more points of sale. Typical containers are a bar fridge, a committee snack shelf, or a single event's stock. |
| catalogue/point-of-sale | A point of sale (POS) is the surface on which SudoSOS transactions are created. Typical examples are the bar terminal during a drink, a committee's order form, or an app instance on an event laptop. A POS is not an organ — it is the place where people buy things. |
| catalogue/product-categories | Product categories classify products taxonomically — e.g. "Beer", "Soda", "Snacks". Every ProductRevision belongs to exactly one category, so a product's category is part of its revision history and can change when the product is edited. |
| catalogue/products | A product is a sellable item in SudoSOS — a beer, a snack, a ticket, a service charge. Products are the lowest-level unit the rest of the system is built on: every purchase is a line on a transaction that points at a specific ProductRevision. |
| catalogue/vat | A VAT group is a named VAT rate that products reference. In the Netherlands the common ones are "Hoog 21%", "Laag 9%", and "Geen 0%", but SudoSOS stores the percentage as a double — Dutch VAT has never had decimal brackets, but politics can change that at any time and the schema would rather not need a migration the day it does. |
| config | - |
| controller/request/inactive-administrative-cost-request | - |
| controller/response/inactive-administrative-cost-response | - |
| controller/response/wrapped-response | - |
| controller/user-notification-preference-controller | - |
| debtors | The debtors module is the orchestrator over the fines entities. A "debtor" in SudoSOS is any user with a negative Balance, just below zero, not specifically below the -5 EUR fine threshold. Whether a user can become one in the first place is gated by User.canGoIntoDebt, off by default, so most accounts cannot purchase past zero. This module is the place where an admin or financial responsible decides what to do about the ones that can and have. |
| entity/notifications/user-notification-preference | - |
| entity/payment-request/payment-request-attempt | - |
| entity/transactions/inactive-administrative-cost | - |
| entity/user | This is the module page of the member-user. |
| entity/wrapped | This is the module page of the wrapped entity. |
| This is the module page of event. | |
| files/templates/bac-letterhead | - |
| fines | A fine is a small penalty (capped at 5 EUR per round) applied to a user with a persistently negative Balance. Fines are handed out in batches as a debtor-recovery step, not as a per-transaction fee. The amount is min(5 EUR, floor(-balance / 5 EUR) * 1 EUR), never negative, so a user at -3.40 EUR gets nothing and a user at -42 EUR still gets only 5 EUR. |
| GEWIS | This is the module page of GEWIS. |
| GEWIS/gewis-db-sync-service | This is the module page of the gewis-db-sync-service. |
| helpers | This is the module page of the ad. |
| helpers/dinero | This is the module page of the dinero-request. |
| helpers/logging | - |
| helpers/params | - |
| html/base.html | - |
| html/document.html | - |
| html/fine-report.html | - |
| html/inactive-administrative-cost-report.html | - |
| html/invoice.html | - |
| html/seller-payout.html | - |
| html/transaction.html | - |
| html/transfer.html | - |
| internal/application | This is the module page of the application. |
| internal/controller | This is the module page of policy. |
| internal/controllers | This is the module page of authentication-controller. |
| internal/cron | This is the module page the cron job service. |
| internal/database | This is the module page of the database. |
| internal/entities | This is the module page of base-entity-without-id. |
| internal/errors | This is the module page of the errors. |
| internal/files | This is the module page of the simple-file-controller. |
| internal/files/pdf | This is the module page of the pdf-able. |
| internal/files/storage | This is the module page of the disk-storage. |
| internal/helpers | This is the module page of the pos-token-verifier. |
| internal/ldap | This is the module page of the ad-service. |
| internal/ldap-sync-service | This is the module page of the ldap-sync-service. |
| internal/mailer | This is the module page of the mailer. |
| internal/maintenance | This is the maintenance script for development setup. It performs maintenance tasks that are normally handled by cron jobs. |
| internal/middleware | This is the module page of the async-validator-middleware. |
| internal/migrations | This is the module page of migrate. |
| internal/notifications | This is the module page of the mailer. |
| internal/pdf | This is the page of pdf-service. |
| internal/pdf/fine-report-pdf-service | This is the page of fine-report-pdf-service. |
| internal/pdf/inactive-administrative-cost-report-pdf-service | This is the page of inactive-administrative-cost-report-pdf-service. |
| internal/pdf/invoice-html-pdf-service | This is the page of invoice-html-pdf-service. |
| internal/pdf/payout-request-pdf-service | This is the page of payout-request-pdf-service. |
| internal/pdf/seller-payout-pdf-service | This is the page of seller-payout-pdf-service. |
| internal/pdf/transaction-pdf-service | This is the page of transaction-pdf-service. |
| internal/pdf/transfer-pdf-service | This is the page of transfer-pdf-service. |
| internal/pdf/user-report-pdf-service | This is the page of user-report-pdf-service. |
| internal/reports | This is the module page of the report-service. |
| internal/server-settings | This is the module page of the server-settings-controller. |
| internal/server-status | This is the module page of the server-status-response. |
| internal/services | - |
| internal/spec | This is the module page of the general-validators. |
| internal/spec/banner-request-spec | This is the module page of the banner-request-spec. |
| internal/spec/container-request-spec | This is the module page of the container-request-spec. |
| internal/spec/duration-spec | This is the module page of the duration-spec. |
| internal/spec/inactive-administrative-cost-spec | This is the module page of the inactive-administrative-cost-spec. |
| internal/spec/invoice-request-spec | This is the module page of the invoice-request-spec. |
| internal/spec/point-of-sale-request-spec | This is the module page of the point-of-sale-request-spec. |
| internal/spec/product-request-spec | This is the module page of the product-request-spec. |
| internal/spec/rbac-request-spec | This is the module page of the rbac-request-spec. |
| internal/spec/string-spec | This is the module page of the string-spec. |
| internal/spec/update-local-request-spec | This is the module page of the update-local-request-spec. |
| internal/spec/update-nfc-request-spec | This is the module page of the update-nfc-request-spec. |
| internal/spec/update-pin-request-spec | This is the module page of the update-pin-request-spec. |
| internal/spec/user-request-spec | This is the module page of the user-request-spec. |
| internal/spec/validation-errors | This is the module page of the validation-errors. |
| internal/subscribers | This is the module page of the subscribers. |
| internal/subscribers/transaction-subscriber | This is the module page of the transaction-subscriber. |
| internal/subscribers/transfer-subscriber | This is the module page of the transfer-subscriber. |
| internal/swagger | This is the module page of the swagger-service. |
| internal/sync-service | This is the module page of the abstract sync-service. |
| internal/sync-service-factory | This is the module page of the sync-service-factory. |
| internal/transformers | This is the module page of the DineroTransformer. |
| internal/user-settings | This is the module page of the user-setting. |
| internal/user-sync-service-factory | This is the module page of the user-sync-service-factory. |
| internal/user-user-service | This is the module page of the abstract sync-service. |
| internal/write-off-pdf-service | This is the page of write-off-pdf-service. |
| invoicing | This is the module page of invoicing. |
| mailer/messages/inactive-administrative-cost-notification | - |
| mailer/messages/transaction-notification | - |
| mailer/messages/user-got-inactive-administrative-cost | - |
| mailer/messages/user-type-updated | - |
| mailer/messages/user-type-updated-with-reset | - |
| migrations/1761324427011-member-authenticator | - |
| migrations/1761328648026-add-organ-membership-index | - |
| migrations/1763399087409-rename-gewis-to-external | - |
| migrations/1764615514906-user-notification-preference | - |
| migrations/1764842063654-add-wrapped-table | - |
| migrations/1765826596888-add-wrapped-organ-member | - |
| migrations/1768697568707-user-setting | - |
| migrations/1769000095806-add-last-seen-to-user | - |
| migrations/1778681972323-add-expiry-to-user | - |
| migrations/1785401380818-add-product-self-service-to-user | - |
| notifications | This is the module page of the notification-types. |
| notifications/channels/abstract-channel | - |
| notifications/channels/mail-channel | - |
| notifications/notification-options | - |
| notifications/notification-registry | - |
| notifications/notifier | - |
| notifications/templates/notification-email-templates | - |
| organ | - |
| payout-requests | A payout-request is a user-initiated withdrawal: a member with a positive Balance asks for the money to be sent to a real bank account. In practice this is mostly the exit hatch for members leaving the association who want their leftover credit back; active members tend to just keep spending it. |
| rbac | A Role is a named permission set. A user picks up a role through one of three paths: their user type maps to it via RoleUserType, an admin assigns it explicitly via AssignedRole, or they inherit it from an organ they belong to via OrganMembership. RoleManager resolves the union of all three on every request. |
| reports | This is the module page of the report. |
| seller-payouts | A seller-payout settles sales credit from SudoSOS to an organ. Every SubTransactionRow that crosses the till credits the container-owner's user account (ORGAN users hold this credit). Once a quarter, or whenever the organ asks for a settlement, a treasurer creates a seller-payout that sweeps the accumulated credit back out to the real-world bank account. |
| service/inactive-administrative-cost-service | - |
| service/sync/sync-manager | - |
| service/sync/user/user-sync-manager | - |
| service/terms-of-service-service | - |
| service/user-expiry-service | - |
| service/user-notification-preference-service | - |
| service/websocket-service | - |
| service/websocket/event-guards | - |
| service/websocket/event-registry | - |
| service/websocket/pos-relation-helper | - |
| service/websocket/room-parser | - |
| service/websocket/room-policy | - |
| service/wrapped-service | - |
| stripe | This is the module page of the stripe-deposit. |
| stripe/payment-request | This is the module page of the payment-request. |
| stripe/payment-request-checkout-service | This is the module page of the payment-request-checkout-service. |
| stripe/payment-request-service | This is the module page of the payment-request-service. |
| stripe/terminal-payment | A Terminal-Payment is a transaction that is immediately paid for using Stripe. This is done by creating a positive transfer of the same total amount as the transaction, and creating it just before the transaction. In practice, TerminalPayments are most often done when people that incidentally want to order something can pay for their order. A SudoSOS account is not necessary. |
| terms-of-service | This is the module page of the terms-of-service-controller. |
| transaction-summaries | This is the module page of the transaction summaries. Not that this module has been created in very strict time constraints, so its implementation is very minimal. https://github.com/GEWIS/sudosos-backend/pull/415 |
| transactions | A Transaction is one purchase at a SudoSOS point of sale: one person paid for a basket of products. The buyer is on the transaction (from); the products and prices live one level down on SubTransactions. |
| transactions/sub-transactions | A SubTransaction is one seller's slice of a Transaction. Where the parent transaction records "this user spent money at this POS", the sub-transaction records "and this much of it goes to this organ". A transaction with one container in the basket has one sub-transaction; a basket that mixes containers from three organs has three. |
| transfers | A Transfer is an explicit money movement on or off a SudoSOS account. Where a Transaction records products bought at a point of sale, a transfer is the raw "X amount moves from A to B" record with no product line. Every deposit, fine, payout, write-off, and invoice settlement becomes a Transfer. |
| users | This is the module page of the user. |
| vouchers | This is the module page of the voucher-group. |
| websocket | This is the module page of the terminal payment relation helper. |
| workers/mail-worker | - |
| write-offs | A write-off zeroes an unrecoverable negative Balance and closes the account it belongs to. Treasurers use it for users who have left the association without settling up: rather than letting a stale debt sit on the books, the write-off cancels it out in one credit transfer and the account is retired. |