Add Basic Architecture Doc

[devlinjunker]

Description

Add Basic Docs to Repo that contain Initial Architecture sections

TODO

• Think about this more...
• Review Mermaid JS (generate UML with markdown)
  • Can we create action that does this with Issues/PRs?
• Complete PR Body
• Updated Architecture/README documents

[devlinjunker]

Should this just be a single revision controlled file? e.g. ./architecture.md that starts basic and is updated with each PR/commit?

Maybe ./docs/architecture.md?

[devlinjunker]

• Add Design doc:
  • what problem you are trying to solve
  • who is this being built for
  • background/domain knowledge/terminology
  • use cases
  • requirements
  • existing solutions (architecture/design decisions)
  • stakeholders

[devlinjunker]

Unsure if this should be in this repo or a different one? Maybe a docs repo?

• Getting Started
• Design (previous comment)
• Architecture
• API
• Styleguide?
• how-to/
  • Add a ... (endpoint/route/component/feature)
  • Build Process
  • Deploy
  • Performance Monitoring?
  • Create Release Artifact

[devlinjunker]

Design docs should have templates for new features (with stuff from previous comment) and should be encouraged prior to any new feature or big change.

Maybe have directory with template file for design docs and sub directories for each feature

e.g.

- design/
|— initial/
|—— (copy of template)
|— template/
|—— (separate files for each bullet point in above comment (stakeholders/usecase/requirements)?)

[devlinjunker]

Should these docs be in a related repo rather than the same repo?

Pros:

• Separate reviews/labeling/projects/processes could be created

Cons:

• we could have github action that checks for design doc for new features if in same repo
  • we could do this with a separate repo though too right?

[devlinjunker]

Include Reference to https://www.uml-diagrams.org/ maybe?

[devlinjunker]

In larger project:

- docs/
|-- design/
|---- initial/
|------ (copy of template)
|---- _template/
|------ assets/
|-------- README.md (links, images, generated charts)
|------ mockups/     **** w/ UI
|-------- README.md (links, photoshop/basalt, html/css)
|------ intro.md (problem, background, stakeholders, research)
|------ architecture.md (tools, services, schemas, api, diagrams)
|------ usecases.md (specific use cases and requirements.. TBD)
|---- README.md (explain how files should be used?)
|-- how-to/
|---- ADD_FEATURE.md
|---- BUILD.md        **** w/ code 
|---- DEPLOY.md      **** w/ code 
|---- MONITOR.md     **** w/ application 
|---- RELEASE.md
|---- STYLE.md

This repo will only have:

- docs/
|-- design/
|---- initial/
|------ (copy of template)
|---- _template/
|------ assets/
|-------- README.md (links, images, generated charts)
|------ intro.md (problem, background, stakeholders, research)
|------ architecture.md (tools, services, schemas, api, diagrams)
|------ usecases.md (specific use cases and requirements.. TBD)
|---- README.md (explain how files should be used?)
|-- how-to/
|---- ADD_FEATURE.md
|---- RELEASE.md
|---- STYLE.md

[devlinjunker]

should this should be a separate repo template.github.doc? template.github.design?

#2 template.github.project should include this

• first thing to write is doc/workflow/ folder for scripts/hooks/actions

[devlinjunker]

moving this to the next template (#2) not in this repo

[devlinjunker]

or maybe this should be part of "github.template-wiki" repository, that builds off of this?

or maybe off of javascript template repo? for mermaid.js