docs: add tech designs folder

- This enables per-line commenting on files and better tracking of changes over time
- Also update just-the-docs look and feel

docs/.gitignore

@@ -0,0 +1,9 @@
+_site/
+.sass-cache/
+.jekyll-cache/
+.jekyll-metadata/
+vendor/
+
+# These are not needed on GH Pages, but are used for local doc development
+Gemfile
+Gemfile.lock

docs/_config.yml

@@ -1,2 +1,3 @@
 remote_theme: pmarsceill/just-the-docs
 include: ['CONTRIBUTING.md']
+color_scheme: carbon

docs/_sass/color_schemes/carbon.scss

@@ -0,0 +1,41 @@
+// @import './color_schemes/dark';
+
+$carbon-blue-30: #a6c8ff;
+$carbon-blue-40: #78a9ff;
+$carbon-blue-60: #0f62fe;
+$carbon-gray-0: #ffffff;
+$carbon-gray-10: #f4f4f4;
+$carbon-gray-50: #8d8d8d;
+$carbon-gray-90: #262626;
+$carbon-gray-100: #161616;
+
+$body-background-color: $carbon-gray-0;
+// $body-heading-color: $grey-dk-300 !default;
+$body-text-color: $carbon-gray-100;
+$code-background-color: $carbon-gray-10;
+$sidebar-color: $carbon-gray-10;
+// $nav-child-link-color: $carbon-blue-30;
+
+$body-font-family: 'IBM Plex Sans', sans-serif;
+$mono-font-family: 'IBM Plex Mono', monospace;
+
+$link-color: $carbon-blue-60;
+
+pre {
+  line-height: 1.2;
+}
+
+h4 code {
+  font-size: 0.75rem;
+  letter-spacing: normal;
+}
+
+blockquote p {
+  color: $carbon-gray-50;
+}
+
+// $base-button-color: #f7f7f7 !default;
+// $btn-primary-color: $purple-100 !default;
+// $table-background-color: $white !default;
+// $search-background-color: $white !default;
+// $search-result-preview-color: $grey-dk-000 !default;

docs/index.md

@@ -1,5 +1,6 @@
 ---
-title: _Home
+title: Home
+nav_order: 1
 ---
 
 # Welcome to the Carbon Platform developer docs!

docs/packages-api.md → docs/packages/api.md

@@ -1,3 +1,7 @@
+---
+parent: Packages
+---
+
 # API package
 
 A package that exports common API utilities used across various other packages and services. These

docs/packages-icons.md → docs/packages/icons.md

@@ -1,3 +1,7 @@
+---
+parent: Packages
+---
+
 # Icons package
 
 This package bundles all project-specific SVG icons in a node module.

docs/packages/index.md

@@ -0,0 +1,5 @@
+---
+title: Packages
+nav_order: 2
+has_children: true
+---

docs/packages-mdx-components.md → docs/packages/mdx-components.md

@@ -1,3 +1,7 @@
+---
+parent: Packages
+---
+
 # MDX Components package
 
 The set of components renderable in MDX files on the Carbon Platform.

docs/packages-micromanage-cli.md → docs/packages/micromanage-cli.md

@@ -1,3 +1,7 @@
+---
+parent: Packages
+---
+
 # Micromanage CLI package
 
 Docs for micromanage are located in the package's [README.md](../packages/micromanage-cli/README.md)

docs/services-data-graph.md → docs/services/data-graph.md

@@ -1,3 +1,7 @@
+---
+parent: Services
+---
+
 # Data-Graph service
 
 ### Service

docs/services/index.md

@@ -0,0 +1,5 @@
+---
+title: Services
+nav_order: 3
+has_children: true
+---

docs/services-logging.md → docs/services/logging.md

@@ -1,3 +1,7 @@
+---
+parent: Services
+---
+
 # Logging service
 
 ### Service

docs/services-web-app.md → docs/services/web-app.md

@@ -1,3 +1,7 @@
+---
+parent: Services
+---
+
 # Web-App service
 
 The Web App service is a Next.js application that serves as the origin server for the

tech-designs/README.md

@@ -0,0 +1,6 @@
+# Tech designs
+
+This is the home of all technical designs for the Carbon Platform.
+
+Each tech design is named as `td-##-title-of-doc.md`, where `##` is a sequentially incrementing
+number and `title-of-doc` is a short title/description of the doc.

tech-designs/_TEMPLATE.md

@@ -0,0 +1,122 @@
+# td-[nn] - [Tech design title]
+
+**Status:** Draft 📝
+
+<!--
+Draft 📝
+Approved ✅
+Canceled 🚫
+-->
+
+## Summary
+
+> Describe the new feature from a technical perspective.
+
+> Describe the problem solved by this feature.
+
+> Describe how it integrates/relates/communicates with existing features/packages/services.
+
+> What needs to be in place prior to this feature being developed?
+
+> What assumptions are being made about those dependencies or about the feature itself?
+
+> What noteworthy things are considered "out of scope" for this feature?
+
+## Research
+
+- [ ] Approved?
+
+**Unanswered questions**
+
+> List any unknowns and unanswered questions that need answers prior to beginning development. Note
+> that **all** of these questions should be answered prior to approving the Research section.
+
+**New technologies**
+
+> List new technologies that need to be explored in detail before beginning development.
+
+**Proofs of concept**
+
+> List proofs of concept that need to be completed before beginning development.
+
+## UI/UX design
+
+- [ ] Approved?
+
+> Does this feature have any associated UI/UX? If so, describe any design that needs to be
+> completed/red-lined prior to development.
+
+## APIs
+
+- [ ] Approved?
+
+**Programmatic APIs**
+
+> List any APIs that will be developed and made available in the `@carbon-platform/api` package,
+> including function/class/method names, parameters, and return values. If this tech design
+> describes a new monorepo package, detail the APIs and exports of that package.
+
+**Data graph**
+
+> List any new query resolvers and/or data models being included in the data-graph and/or data-graph
+> API package.
+
+**Messages**
+
+> List any new/changed RabbitMQ messages introduced by this feature, the message payload structure
+> associated with them, whether they are queries or emits, and their expected return values (for
+> queries).
+
+## Security
+
+- [ ] Approved?
+
+> What new data is created/stored/collected/transmitted by this feature? How is that data secured?
+> Who is allowed to access it? How is that access controlled? Think like a hacker. How might someone
+> attempt to break or abuse this feature?
+
+## Error handling
+
+- [ ] Approved?
+
+> Ignore the happy path. What can go wrong with this feature? How will the error conditions manifest
+> through the APIs? How will users be informed about these errors?
+
+## Test strategy
+
+- [ ] Approved?
+
+> How will the new feature be tested? (e.g. unit tests, manual verification, automated e2e testing,
+> etc.) What interesting edge cases should be considered and tested?
+
+## Logging
+
+- [ ] Approved?
+
+> Detail any FFDC data (info, warning, error, debug logs) to be captured by this feature. Pretend
+> you're on-call for supporting the Platform. In the event something breaks and all you have to go
+> by is a list of log entries (i.e. you can't reproduce the failure yourself, but users are
+> reporting problems), what information would you need to be able to pinpoint the source of a
+> production-site failure? Additional info: [Logging service](/docs/services-logging.md)
+
+## File and code layout
+
+- [ ] Approved?
+
+> Describe how the files and code for this feature will fit into the rest of the mono repo. Will
+> there be a new package/service? Are there existing files/directories in which the new logic should
+> live?
+
+## Issue and work breakdown
+
+- [ ] Approved?
+
+> List any issues that should be created prior to starting work on this feature.
+
+**Epics**
+
+- [ ]
+
+**Issues**
+
+- [ ]

tech-designs/td-01-replace-fs-cache-with-redis.md

@@ -0,0 +1,130 @@
+# td-01 - Replace fs-cache with redis
+
+**Status:** Canceled 🚫
+
+<!--
+Draft 📝
+Approved ✅
+Canceled 🚫
+-->
+
+## Summary
+
+The web app uses a [Node.js cache-manager](https://www.npmjs.com/package/cache-manager) to cache all
+GitHub responses to prevent the web app from getting GitHub API rate limited. These GitHub requests
+vary from fetching repository information, traversing GitHub trees, to primarily fetching GitHub
+file content to read carbon.yml files and MDX files for web page content.
+
+We're currently using a file system store engine
+(https://www.npmjs.com/package/cache-manager-fs-hash), which was chosen during v1 preview
+prototyping as a quick and easy way to prevent GitHub API rate limits.
+
+As we index more content (asset documentation pages), each GitHub request per MDX file adds to the
+amount of cached responses. Our current build pipeline does not persist cached files written to disk
+between builds.
+
+As the amount of indexed content grows, so does the risk of our production GitHub access tokens
+getting rate limited which could leave us with a production environment void of all content.
+
+**Potential solution**
+
+To mitigate that risk, until we can create proper back-end services for this, what if we added Redis
+stores for staging and production? It looks like we could use a Redis store listed here:
+https://github.com/BryanDonovan/node-cache-manager#store-engines
+
+Those Redis store engines _should_ share the same API as `cache-manager-fs-hash`, so that _should_
+require minimal web app changes.
+
+We could keep the
+[1 hour TTL](https://github.com/carbon-design-system/carbon-platform/blob/main/services/web-app/lib/file-cache.js#L24)
+for cached responses, so for Next.js ISR pages, content from GitHub would be at most 1 hour stale.
+
+With a Redis cache, our production builds should be faster because there's a greater chance of a
+cache hit.
+
+We could use a Redis cache for local development too, or for simplicity, keep that with the current
+file system cache.
+
+**TL;DR:**
+
+In the event that our production environment gets rate limited by GitHub, because the Redis cache
+would be persisted, we wouldn't lose web app content between deploys. Also, it would be neat to see
+how many keys would get cached in Redis, to give us a better idea of to-be infrastructure needs to
+manage GitHub content.
+
+TODO: vv Everything below this vv
+
+## Research
+
+- [ ] Approved?
+
+- **Unanswered questions**
+  - List any unknowns and unanswered questions that need answers prior to beginning development
+- **New technologies**
+  - List new technologies that need to be explored in detail before beginning development
+- **Proofs of concept**
+  - List proofs of concept that need to be completed before beginning development
+
+## UI/UX design
+
+Does this feature have any associated UI/UX? If so, describe any design that needs to be
+completed/red-lined prior to development.
+
+## APIs
+
+- [ ] Approved?
+
+- **Programmatic APIs**
+  - List any APIs that will be developed and made available in the `@carbon-platform/api` package,
+    including function/class/method names, parameters, and return values.
+- **Messages**
+  - List any new/changed RabbitMQ messages introduced by this feature, the message payload structure
+    associated with them, whether they are queries or emits, and their expected return values (for
+    queries).
+
+## Test strategy
+
+- [ ] Approved?
+
+How will the new feature be tested? (e.g. unit tests, manual verification, automated e2e testing,
+etc.)
+
+What interesting edge cases should be considered and tested?
+
+## Security
+
+- [ ] Approved?
+
+What new data is created/stored/collected/transmitted by this feature? How is that data secured? Who
+is allowed to access it? How is that access controlled?
+
+Think like a hacker. How might someone attempt to break or abuse this feature?
+
+## Error handling
+
+Ignore the happy path. What can go wrong with this feature? How will the error conditions manifest
+through the APIs? How will users be informed about these errors?
+
+## Logging
+
+- [ ] Approved?
+
+Detail any FFDC data (info, warning, error, debug logs) to be captured by this feature.
+
+## File and code layout
+
+- [ ] Approved?
+
+Describe how the files and code for this feature will fit into the rest of the mono repo. Will there
+be a new package/service? Are there existing files/directories in which the new logic should live?
+
+## Issue and work breakdown
+
+- [ ] Approved?
+
+List any issues that should be created prior to starting work on this feature
+
+- **Epics**
+  - ...
+- **Issues**
+  - ...