accounts-svc

Accounts Machine

Accounts Machine is a UK VAT filing application. Users use gnucash or other tools to manage their accounts, and then upload the account files to Accounts Machine to file VAT returns with HMRC. Accounts Machine manages the linking of user accounts to HMRC, and the submission of VAT return records using HMRC's MTD.

Other functionality exists for Companies House and HMRC Corporation Tax filing, but this is incomplete and needs further work, and so is switched off in the production application.

Overview

This repository is the back-end for accountsmachine.io. The front-end, accounts-web is a separate repository.

                     ,-----------------.
                     |                 |        ,--------------.
  browser ------------> proxy ----------------> | accounts-svc |
     |               |    |            |        `--------------'
     |               |    '-- web app  |           |          |
     |               |                 |           |          |
     |               |   accounts-web  |           |          |
     |               `-----------------'           v          v
     |                                         ,--------.  ,------.
     '---------------------------------------->| Stripe |  | HMRC |
                                               `--------'  `------'

The back-end is deployed to production in a container.

Backend

This is a simple service with HTTP endpoints. The backend implements Firebase authentication and uses the auth token to determine user access. It communicates with Google Cloud for storage. Also communicates with Stripe for payments (where used) and HMRC for VAT filing.

Deployment environments

There are 4 deployment environments:

• local: For running the accounts-web and accounts-svc locally for development & testing. Uses the dev account for authentication and storage.
• dev: Application deployment to a development account for semi-realistic testing. The VAT service is a dummy one, so there is no interaction with HMRC live services.
• stage: Application deployment to a stage account. The backend service uses the prod account for authentication and storage. Filing is to the HMRC live, as for prod. This is only for 'testing' that the live build works, can't be used to 'test' filing procedures as the filing backend is real.
• production: Deployment is to the prod account. Uses prod auth, prod storage, and live filing systems.

Domain restrictions restrict who can log in to dev/stage. Most normal users can only access 'prod'.

Deployment

Deployment is using Github actions and Pulumi scripts. Actions is used to build the container. Pulumi is used to push the container to Google Cloud and run it in Cloud Run service.

There are two secrets in use:

• The 'configuration' file is held as a Github secret and deployed to Google Cloud as a secret.
• There is also a service account key generated by Pulumi and deployed as a secret.

The 'configuration' secret contains some other secrets e.g. the HMRC MTD accounts secret, a Companies House secret, and Stripe secrets.

The pipelines have full access to the cloud environments, and so care needs to be taken to review changes to the Github actions.

Building the container

This is taken care of by the Github actions script.

Running locally

You need to create a complex configuration file, say config-local.json:

{

    "port": 8081,

    "project": "MY-GCP-PROJECT",
    "bucket": "MY-GCP-BUCKET",

    "stripe-public": "...",
    "stripe-secret": "...",
    "stripe-webhook-key": "...",

    "seller-name": "example.com",
    "seller-vat-number": "GB123456789",

    "vat-rate": 20,

    "jsonnet-base": "ixbrl-reporter-jsonnet/",
    "config-base": "base/",

    "vat-auth-url": "https://VAT-TEST.example.com",
    "vat-api-url": "https://VAT-TEST.example.com",
    "vat-client-id": "id1",
    "vat-client-secret": "secretasdasdlkaskdjaskdj",
    "redirect-uri": "http://localhost:8080/api/vat/receive-token",

    "companies-service-api-key": "testtesttest",
    "companies-service-url": "https://COMPANIES-TEST-URL.example.com/",

    "audience": "MY-GCP-PROJECT",
    "algorithms": ["RS256"],

    "application-id": "alsdkaslkdjasldkjaslkdjad"

}

The Companies House and VAT URL information can be configured to talk to test services designed for use with this application. You can run these locally if you want:

• VAT test service
• Companies House test

The seller information is only used on receipts. The stripe keys you can set up if you want, but are only used for paying transactions.

The service communicates with Google Cloud so you need to be logged in using gcloud, and the application will just use your application default credentials.

The directory ixbrl-report-jsonnet is used. Unpack this repo in that directory.

Run the service:

export PYTHONPATH=.
scripts/am-svc config-local.json

You also need to start the front-end locally. See accounts-web

LICENCE

Accounts Machine software, account-web, accounts-svc
Copyright (C) 2021-2023, Accounts Machine Limited, cybermaggedon.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

See LICENSE.