[Issue 188] Architecture diagram

[SammySteiner]

Summary

Fixes #188

Time to review: 30

Changes proposed

Added a architecture readme file with several diagrams.

Context for reviewers

I used mermaid to create the diagrams as code to help us maintain them going forward. However, I ran into a few challenges:

• Mermaid does not make it easy to include images so i couldn't use aws service icons
• Mermaid has issues when drawing lines between nested subgraphs so I had to settle for higher order nodes
• I couldn't really get the hang of formatting and direction of the diagrams, so that may be suboptimal

It would be really helpful to get feedback on both the diagrams themselves and what they are missing, as well as my implementation of mermaid because I'm sure I have a lot to learn there.

[SammySteiner]

Apparently the font-awesome icons don't show up in github 🤦
https://mermaid.js.org/syntax/flowchart.html#basic-support-for-fontawesome

https://github.com/orgs/community/discussions/11940

[gcarson-bit]

Great job on the mermaid diagram--really neat stuff! My only question/comment is regarding the database - shouldn't the replica DB be the same as the Postgres DB?

[SammySteiner]

Great job on the mermaid diagram--really neat stuff! My only question/comment is regarding the database - shouldn't the replica DB be the same as the Postgres DB?

@gcarson-bit Good question, I wasn't sure what to do with that. I imagine while we're using the replica database living in the microhealth tenant, those are definitely separate. But once we set up replication, I wasn't sure if we would keep the logging and user access tables for our api in a separate db or just in separate tables in the replicated database.

[widal001]

This looks awesome!! I left a few comments about some of the details hard coded in the diagram that we can discuss further in slack.

Once we reach alignment on that question, I'll approve!

[widal001]

Love the links to the relevant ADRs!!! Great addition.

[widal001]

I know this is in a private subnet so there shouldn't necessarily be a security concern, but my instinct would be avoid hard coding IP addresses and ports into the diagram -- unless you feel like including those details here provides important system-design-level information.

[acouch]

I would agree w/ removing the actual address.

[widal001]

Same comment as above, I'd exclude this from the final diagram.

[widal001]

Same comment above re: IP address and Port details

[acouch]

Looks great! Along with the comment above, I would also either remove the "IAM," "SSM," and "Cloudwatch" or integrate them into the flow. Does cloudwatch trigger the container update, or is it just for logging? If it is the latter, pulling it out into its own graph could help indicate that

[lucasmbrown-usds]

A couple stray thoughts:

1. Will the front-end point at the API endpoints of the backend through the public internet (i.e., there's no privileged access of the front-end)?

2. To convert data from the existing data format (in the replica DB) into a streamlined, new data format (in the Postgres DB), there's probably some type of conversion task (maybe it's stream processing where changes in the replica trigger a task to update data in the new Postgres DB? or maybe batch processing). Is that represented here as part of the ECS Back-End Tasks, or do we want to call it out separately?

Otherwise looks great!

[acouch]

Will the front-end point at the API endpoints of the backend through the public internet (i.e., there's no privileged access of the front-end)?

At some point. I would imagine that the need for HHS internal users to edit the text would be the driver there. We can update the diagram once we make that change.

To convert data from the existing data format (in the replica DB) into a streamlined, new data format (in the Postgres DB), there's probably some type of conversion task (maybe it's stream processing where changes in the replica trigger a task to update data in the new Postgres DB? or maybe batch processing). Is that represented here as part of the ECS Back-End Tasks, or do we want to call it out separately?

We are still doing discovery (#369 ) on what service or set of tools we will do that with. I think the replication could be a separate diagram as you've noted, once we have a strategy in place. I do think we could be more explicit about that relationship in this diagram.

[SammySteiner]

I'd like to keep those in the general architecture as one of the goals is to document all the AWS services we're using, but I like the idea of subgraphing them to identify how they are being used.

[acouch]

Looks fantastic!