Architecture

https://raw.githubusercontent.com/stackplanet/sourcestack/master/architecture.png

Code organisation

Code is organised in the following top-level folders:

• ui: client-side user interface
• api: REST api
• infra: cloud infrastructure (Lambda, DynamoDB etc)
• scripts: scripts run via npm run ...

Generic vs app-specific code

The template includes "generic" code (code that would likely be the same across different applications) and app-specific code.

Generic code can be found in:

• ui/src/generic - login pages, sign up pages, forgot password pages etc.
• scripts - the scripts documented above, e.g. build, deploy etc.
• api/src/generic - authentication handler, backend configuration etc.
• infra/src/generic - the base stack defined in CDK.

Of course, you can still modify generic code if it doesn't suit your needs.

infra

• The 'generic' part of the infrastructure is in infra/src/generic/basestack.ts
• The app-specific part of the infrastructure (e.g. DynamoDB tables) is in infra/src/stack.ts

ui

• The template uses the excellent Mithril library, with JSX syntax, as a simple alternative to React.
• The template also uses Tailwind CSS for atomic CSS. I recommend the Tailwind CSS IntelliSense VSCode plugin.

api

• URLs that start with /api are routed to the api layer.

Security

• The login pages (login, sign up, forgot password) are in ui/src/generic/login.
• The REST api used by these pages is in api/src/generic/authhandler.ts.
• All endpoints in this api start with /api/auth
• Once logged in, credentials are stored in the auth_token and refresh_token cookies. auth_token contains a JWT issued by the Cognito user pool, and is valid for 1 hour. refresh_token contains a refresh token issued by the user pool that can be used to refresh the auth_token. The refresh token is valid for 30 days by default; this can be controlled via the CDK template.
• Any api endpoint that starts with /api/private can only be accessed by logged in users (i.e. requests with the auth_token cookie). Non-logged in users will receive a 401 error when accessing these endpoints.
• The details of the logged in user is stored by authhandler as a field user on the Express request object:

    app.get('/api/hello', async (req, res) => {
        if (req.user){
            res.send('Hello ' + req.user.userId);
        }
        else {
            res.send('Hello anonymous');
        }
    });