diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml new file mode 100644 index 0000000..5c07195 --- /dev/null +++ b/.github/workflows/ci.yaml @@ -0,0 +1,26 @@ +name: CI Product Central Wiki to Pages + +on: + push: + branches: ["main"] + paths: + - "docs/**" + +jobs: + build: + runs-on: ubuntu-latest + defaults: + run: + working-directory: ./docs + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: '3.3' + bundler-cache: true + cache-version: 0 + working-directory: '${{ github.workspace }}/docs' + - name: Build with Jekyll + run: bundle exec jekyll build \ No newline at end of file diff --git a/.github/workflows/pages.yaml b/.github/workflows/pages.yaml new file mode 100644 index 0000000..a99995a --- /dev/null +++ b/.github/workflows/pages.yaml @@ -0,0 +1,51 @@ +name: Deploy Product Central Wiki to Pages + +on: + push: + branches: ["main"] + paths: + - "docs/**" + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: '3.3' + bundler-cache: true + cache-version: 0 + - name: Setup Pages + id: pages + uses: actions/configure-pages@v5 + - name: Build with Jekyll + run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" + env: + JEKYLL_ENV: production + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: "docs/_site/" + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/.gitignore b/.gitignore index 732fd0a..625cdaf 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +# Ignore Terraform files **/.terraform/* .terraform* terraform.tfstate @@ -8,4 +9,14 @@ terraform/terraform.tfvars *.backup *.tfvars *.tfvars.json -env.json \ No newline at end of file +env.json + +# Ignore the default location of the built site, and caches and metadata generated by Jekyll +_site/ +.sass-cache/ +.jekyll-cache/ +.jekyll-metadata + +# Ignore folders generated by Bundler +.bundle/ +vendor/ \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..e4093f1 --- /dev/null +++ b/Makefile @@ -0,0 +1,10 @@ +.PHONY: install-docs serve-docs build-docs + +install-docs: + cd docs && bundle install + +serve-docs: + cd docs && bundle exec jekyll serve + +build-docs: + cd docs && bundle exec jekyll build \ No newline at end of file diff --git a/README.md b/README.md index 909d3ea..6cf0f78 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,69 @@ -# Software Architectures +# Product Central Architecture -Collection of Software Architectures / Golden Path for Product Central. \ No newline at end of file +Welcome to the Product Central Architecture repository. This space is designed to provide comprehensive guidance and resources for contributors and users of Product Central's reference architecture templates. + +## Overview + +Product Central provides a set of reference architecture templates to help developers and teams streamline the development and deployment of their applications. These templates offer best practices, standardized structures, and ready-to-use components, ensuring consistency and quality across projects. + +## Getting Started + +### Key Sections + +1. **Introduction**: Learn about Product Central, its mission, and the benefits of using reference architecture templates. +2. **Contributing**: Detailed guidelines on how to contribute to the repository, including forking, cloning, creating content, and raising pull requests. +3. **Templates**: Explore the various templates available, their use cases, and detailed documentation. +4. **Documentation**: Access comprehensive documentation on each template, including TechDocs and Architectural Decision Records (ADRs). +5. **Support**: Find resources for troubleshooting, support channels, and contact information for repository maintainers. + +## Introduction + +Product Central aims to standardize and simplify the development process by providing reference architecture templates that embody best practices and scalable solutions. These templates help teams accelerate their projects and ensure they are built on robust, well-defined foundations. + +### Reference Architecture + +Reference architecture serves as a blueprint for designing and implementing systems. It encapsulates best practices, guidelines, and standardized components to create a robust and scalable architecture. + +#### Benefits of Reference Architecture: + +- **Guidance**: Provides clear guidelines on the structure and components of the system. +- **Reusability**: Components and patterns can be reused across different projects, saving time and effort. +- **Quality**: Ensures that the system adheres to best practices and industry standards. + +### Benefits of Using Product Central Templates + +- **Consistency**: Maintain a consistent structure across projects. +- **Best Practices**: Leverage industry best practices embedded in the templates. +- **Time-Saving**: Reduce development time with ready-to-use components. +- **Scalability**: Build scalable and maintainable applications. + +## Contributing + +Interested in contributing? Visit our [Contributing Guide](https://github.com/99x/product-central-architectures/wiki/Contributing-to-Product-Central-Reference-Architecture-Templates) to learn how you can add value to our repository. Whether you’re improving existing templates or creating new ones, your contributions are welcome and valued. + +## Templates + +Our repository includes a variety of templates tailored for different use cases. Each template is thoroughly documented to help you understand its purpose and how to integrate it into your projects. + +Explore our templates: + +- **[AWS Fullstack App](https://github.com/99x/product-central-architectures/tree/main/architectures/github/aws-fullstack-app)** +- **[99x Design System](https://github.com/99x/product-central-architectures/tree/main/architectures/github/99x-design-system)** +- **[Product Central on AWS](https://github.com/99x/product-central-architectures/tree/main/architectures/github/pdp-aws)** + +## Documentation + +Documentation is key to understanding and effectively using our templates. Each template comes with: + +- **TechDocs**: Detailed technical documentation explaining the template’s purpose, setup, and usage. +- **ADRs**: Architectural Decision Records that capture the reasoning behind key technical decisions. + +## Support + +Need help? Reach out to the Product Central Team and we are happy to assist you! + +## Contact Us + +For any queries or further assistance, please reach out to the repository maintainers or join our community discussions on GitHub. + +Thank you for being a part of the Product Central community. Together, we can build better, faster, and more scalable solutions. diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 0000000..5b91d6e --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,7 @@ +source 'https://rubygems.org' + +gem "jekyll", "~> 4.3.3" # installed by `gem jekyll` +# gem "webrick" # required when using Ruby >= 3 and Jekyll <= 4.2.2 + +gem "just-the-docs", "0.10.0" # pinned to the current release +# gem "just-the-docs" # always download the latest release \ No newline at end of file diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock new file mode 100644 index 0000000..452d90c --- /dev/null +++ b/docs/Gemfile.lock @@ -0,0 +1,91 @@ +GEM + remote: https://rubygems.org/ + specs: + addressable (2.8.7) + public_suffix (>= 2.0.2, < 7.0) + bigdecimal (3.1.8) + colorator (1.1.0) + concurrent-ruby (1.3.4) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + eventmachine (1.2.7) + ffi (1.17.0-arm64-darwin) + ffi (1.17.0-x86_64-linux-gnu) + forwardable-extended (2.6.0) + google-protobuf (4.28.0-arm64-darwin) + bigdecimal + rake (>= 13) + google-protobuf (4.28.0-x86_64-linux) + bigdecimal + rake (>= 13) + http_parser.rb (0.8.0) + i18n (1.14.5) + concurrent-ruby (~> 1.0) + jekyll (4.3.3) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 1.0) + jekyll-sass-converter (>= 2.0, < 4.0) + jekyll-watch (~> 2.0) + kramdown (~> 2.3, >= 2.3.1) + kramdown-parser-gfm (~> 1.0) + liquid (~> 4.0) + mercenary (>= 0.3.6, < 0.5) + pathutil (~> 0.9) + rouge (>= 3.0, < 5.0) + safe_yaml (~> 1.0) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-sass-converter (3.0.0) + sass-embedded (~> 1.54) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + just-the-docs (0.10.0) + jekyll (>= 3.8.5) + jekyll-include-cache + jekyll-seo-tag (>= 2.0) + rake (>= 12.3.1) + kramdown (2.4.0) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.9.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.4.0) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (6.0.1) + rake (13.2.1) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) + ffi (~> 1.0) + rexml (3.3.7) + rouge (4.3.0) + safe_yaml (1.0.5) + sass-embedded (1.78.0-arm64-darwin) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-x86_64-linux-gnu) + google-protobuf (~> 4.27) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + unicode-display_width (2.5.0) + webrick (1.8.1) + +PLATFORMS + arm64-darwin + x86_64-linux-gnu + +DEPENDENCIES + jekyll (~> 4.3.3) + just-the-docs (= 0.10.0) + +BUNDLED WITH + 2.5.9 \ No newline at end of file diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..e151def --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,33 @@ +title: Product Central Architectures +description: Collection of Software Architectures / Golden Path for Product Central buckets bundled with TechDocs and ADR. +theme: just-the-docs + +logo: /assets/img/product-central-logo-light.svg +favicon_ico: /assets/img/product-central-icon-light.svg + +url: https://99x.github.io/product-central-architectures + +aux_links: + Template Repository: https://github.com/99x/product-central-architectures + +search_enabled: true + +search: + heading_level: 2 + previews: 3 + preview_words_before: 5 + preview_words_after: 10 + tokenizer_separator: /[\s/]+/ + rel_url: true + button: false + focus_shortcut_key: 'k' + +mermaid: + version: "9.1.3" + +nav_enabled: true + +heading_anchors: true + +color_scheme: light + diff --git a/docs/assets/img/product-central-icon-light.svg b/docs/assets/img/product-central-icon-light.svg new file mode 100644 index 0000000..ffaf0fd --- /dev/null +++ b/docs/assets/img/product-central-icon-light.svg @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/assets/img/product-central-logo-light.svg b/docs/assets/img/product-central-logo-light.svg new file mode 100644 index 0000000..7492327 --- /dev/null +++ b/docs/assets/img/product-central-logo-light.svg @@ -0,0 +1,26 @@ + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/contributing/creating-content.md b/docs/contributing/creating-content.md new file mode 100644 index 0000000..2293556 --- /dev/null +++ b/docs/contributing/creating-content.md @@ -0,0 +1,261 @@ +--- +title: Creating Content +layout: default +parent: Contributing +nav_order: 3 +--- + +# Creating Content + +1. **Code Placement**: Place all code files within the `content` folder. +2. **Catalog Information**: Declare the Product Central (PC) component within the `catalog-info.yaml` file. Follow the template format provided below. +3. **Template Definition**: Define the scaffolder template in the `template.yaml` file using the example provided below. +4. **Updating Showcase Templates**: Update the RA's path in the `showcase-templates.yaml`. + +### Example `template.yaml` +```yaml +apiVersion: scaffolder.backstage.io/v1beta3 +kind: Template +metadata: + name: aws-fullstack-app + title: AWS Fullstack App + description: Fullstack App deployed in AWS + annotations: + backstage.io/adr-location: https://github.com/99x/product-central-architectures/tree/main/architectures/docs/decisions/aws-fullstack-app + backstage.io/techdocs-ref: url:https://github.com/99x/product-central-architectures/tree/main/architectures/docs/techdocs/aws-fullstack-app + tags: + - aws + - full-stack + - nextjs + - nestjs + - micro-frontend + - nx + - module-federation + - server + - infrastructure + - reference-architecture + links: + - url: https://github.com/99x/product-central-architectures + title: 99x Product Central Architectures + icon: dashboard + +spec: + owner: user:99xadmin + type: service + + parameters: + - title: Provide information about the component + required: + - name + - repoUrl + - description + properties: + name: + title: Name + type: string + description: Unique name of the component + ui:autofocus: true + maxLength: 50 + pattern: "^[a-zA-Z0-9-]*$" + ui:help: "Hint: Name should only contain alphanumeric characters and hyphens" + ui:options: + rows: 5 + repoUrl: + title: Repository Location + type: string + ui:field: RepoUrlPicker + ui:options: + allowedHosts: + - github.com + description: + title: Description + type: string + description: A brief description of the component and its purpose + ui:options: + rows: 5 + + - title: Provide information about applications + required: + - coreAppName + - remoteAppName + - serverAppName + properties: + coreAppName: + title: What would you like to name the client core application? + type: string + description: The name of the client core application + maxLength: 50 + pattern: "^[a-zA-Z0-9-]*$" + ui:help: "Hint: Name should only contain alphanumeric characters and hyphens" + default: core + remoteAppName: + title: What would you like to name the first client remote application? (You can always add more remote applications later) + type: string + description: The name of the genesis client remote application + maxLength: 50 + pattern: "^[a-zA-Z0-9-]*$" + ui:help: "Hint: Name should only contain alphanumeric characters and hyphens" + default: remote + serverAppName: + title: What would you like to name the server application? + type: string + description: The name of the server application + maxLength: 50 + pattern: "^[a-zA-Z0-9-]*$" + ui:help: "Hint: Name should only contain alphanumeric characters and hyphens" + default: server + + - title: Provide information about the deployment environment and credentials + required: + - project + - environment + - awsRegion + - awsAccessKeyId + - awsSecretAccessKey + - bucketName + properties: + project: + title: Project + type: string + description: Specify the project name for AWS resources + maxLength: 50 + pattern: "^[a-zA-Z0-9-]*$" + ui:help: "Hint: Name should only contain alphanumeric characters and hyphens" + environment: + title: Environment + type: string + description: Choose the environment to deploy to + enum: + - dev + - demo + - prod + default: dev + awsAccessKeyId: + title: AWS Access Key ID + type: string + description: The AWS access key ID to access the AWS resources + ui:field: Secret + awsSecretAccessKey: + title: AWS Secret Access Key + type: string + description: The AWS secret access key to access the AWS resources + ui:field: Secret + awsRegion: + title: Default Region + type: string + description: The default region to deploy the application + enum: + - us-east-1 + - us-west-1 + - us-west-2 + - eu-west-1 + - eu-west-2 + - ap-southeast-1 + - ap-southeast-2 + - ap-northeast-1 + - ap-northeast-2 + default: ap-southeast-1 + bucketName: + title: S3 Bucket Name + type: string + description: The name of the S3 bucket to store the Terraform state file + default: client-bucket + + steps: + - id: fetch-base + name: Fetch Base + action: fetch:template + input: + url: ./content + copyWithoutTemplating: + - "**/.github/**" + - "./**/.github/**" + values: + name: ${{ parameters.name }} + slug: ${{ parameters.repoUrl | projectSlug }} + description: ${{ parameters.description }} + coreAppName: ${{ parameters.coreAppName }} + remoteAppName: ${{ parameters.remoteAppName }} + serverAppName: ${{ parameters.serverAppName }} + + - id: publish + name: Publish + action: publish:github + input: + allowedHosts: ["github.com"] + description: ${{ parameters.description }} + repoUrl: ${{ parameters.repoUrl }} + repoVisibility: private + defaultBranch: main + gitAuthorName: 99xproductcentral + gitAuthorEmail: productcentral@99x.io + secrets: + AWS_ACCESS_KEY_ID: ${{ parameters.awsAccessKeyId }} + AWS_SECRET_ACCESS_KEY: ${{ parameters.awsSecretAccessKey }} + AWS_REGION: ${{ parameters.awsRegion }} + + - id: github-action + name: Provision Infrastructure + action: github:actions:dispatch + input: + workflowId: "init-infra.yaml" + repoUrl: ${{ parameters.repoUrl }} + branchOrTagName: "main" + workflowInputs: + parameters: ${{ parameters | dump }} + + - id: register + name: Register + action: catalog:register + input: + repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }} + catalogInfoPath: "/catalog-info.yaml" + + output: + links: + - title: Repository + url: ${{ steps['publish'].output.remoteUrl }} + - title: Open in catalog + icon: catalog + entityRef: ${{ steps['register'].output.entityRef }} + - title: CloudFront Distribution ID + url: ${{ steps['github-action'].output.cloudfront_distribution_id }} +``` + +### Example `catalog-info.yaml` + +```yaml +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: ${{ values.name | dump }} + annotations: + github.com/project-slug: ${{ values.slug }} + backstage.io/adr-location: https://github.com/99x/product-central-architectures/tree/main/architectures/docs/decisions/99x-design-system + backstage.io/techdocs-ref: url:https://github.com/99x/product-central-architectures/tree/main/architectures/docs/techdocs/99x-design-system + description: ${{ values.name }} is a design system that is used to build user interfaces for 99x products. + tags: + - storybook + - design-system + - reference-architecture + links: + - url: https://github.com/99x/product-central-architectures + title: 99x Product Central Architectures + icon: dashboard +spec: + type: service + owner: user:99xadmin + lifecycle: production + system: productcentral +``` + +### Annotations + +Ensure to use the following annotations in your `template.yaml` and `catalog-info.yaml`: +- `backstage.io/techdocs-ref: url:https://github.com/99x/product-central-architectures/tree/main/architectures/docs/techdocs/` +- `backstage.io/adr-location: https://github.com/99x/product-central-architectures/tree/main/architectures/docs/decisions/` + +Refer to the formats of the documentation from the following examples: +- TechDocs: [aws-fullstack-app](https://github.com/99x/product-central-architectures/tree/main/architectures/docs/techdocs/aws-fullstack-app) +- ADR: [aws-fullstack-app](https://github.com/99x/product-central-architectures/tree/main/architectures/docs/decisions/aws-fullstack-app) + diff --git a/docs/contributing/folder-structure.md b/docs/contributing/folder-structure.md new file mode 100644 index 0000000..d64b513 --- /dev/null +++ b/docs/contributing/folder-structure.md @@ -0,0 +1,14 @@ +--- +title: Folder Structure +layout: default +parent: Contributing +nav_order: 2 +--- + +# Adhering to the Folder Structure + +Ensure that you follow the prescribed folder structure. All contributions should be developed within the `github/` folder path. + +Refer to the [aws-fullstack-app](https://github.com/99x/product-central-architectures/tree/main/architectures/github/aws-fullstack-app) template as a primary example. + +Consistency in structure helps maintain clarity and organization across all contributions. \ No newline at end of file diff --git a/docs/contributing/getting-started.md b/docs/contributing/getting-started.md new file mode 100644 index 0000000..0ec425b --- /dev/null +++ b/docs/contributing/getting-started.md @@ -0,0 +1,18 @@ +--- +title: Getting Started +layout: default +parent: Contributing +nav_order: 1 +--- + +# Getting Started + +### Fork the Repository +Begin by forking the main repository located at [99x/product-central-architectures](https://github.com/99x/product-central-architectures). This creates a personal copy of the repository under your GitHub account. + +### Clone the Repository +Clone your forked repository to your local machine using the following command: +```bash +git clone https://github.com/your-username/product-central-architectures.git +``` +Replace `your-username` with your GitHub username. \ No newline at end of file diff --git a/docs/contributing/index.md b/docs/contributing/index.md new file mode 100644 index 0000000..d9e426b --- /dev/null +++ b/docs/contributing/index.md @@ -0,0 +1,12 @@ +--- +title: Contributing +layout: default +nav_order: 2 +description: "Contributing to Product Central Architectures" +permalink: /contributing +has_children: true +--- + +# Contributing to Product Central Architectures + +This section provides detailed information on how to contribute to the Product Central Architectures project. It covers everything from getting started to submitting your changes. \ No newline at end of file diff --git a/docs/contributing/submitting-changes.md b/docs/contributing/submitting-changes.md new file mode 100644 index 0000000..c6b084d --- /dev/null +++ b/docs/contributing/submitting-changes.md @@ -0,0 +1,36 @@ +--- +title: Submitting Changes +layout: default +parent: Contributing +nav_order: 6 +--- + +# Submitting Changes + +## Committing and Pushing Changes + +1. **Commit Changes**: Once your changes are ready, commit them to your local repository. + ```bash + git add . + git commit -m "Your detailed commit message" + ``` +2. **Push Changes**: Push your commits to your forked repository. + ```bash + git push origin main + ``` + +## Raising a Pull Request (PR) + +- **PR Submission**: Navigate to the main repository and raise a Pull Request (PR) from your fork. This notifies the repository maintainers that your contribution is ready for review. + +## PR Review Process + +1. **Review by Leads**: The repository leads will review your PR. +2. **Approval**: If the PR meets the standards, it will be merged into the main branch. +3. **Changes Requested**: If changes are requested, address the feedback and push the updated changes to your fork. + +## Completion + +The contribution process is completed once your PR is merged into the main branch of the `99x/product-central-architectures` repository. + +By following these steps, you can ensure a smooth contribution process that aligns with the standards and practices of Product Central. Your contributions are valuable and appreciated in enhancing the overall architecture templates. \ No newline at end of file diff --git a/docs/contributing/testing.md b/docs/contributing/testing.md new file mode 100644 index 0000000..e92573c --- /dev/null +++ b/docs/contributing/testing.md @@ -0,0 +1,15 @@ +--- +title: Testing +layout: default +parent: Contributing +nav_order: 5 +--- + +# Testing the Template Manifest + +To test the scaffolder of the template: + +1. Login to the Product Central application +2. Go to the [Template Editor](https://app.productcentral.io/create/edit) section +3. Choose `Edit Template Form` +4. Follow the prompts to test your template \ No newline at end of file diff --git a/docs/contributing/writing-documentation.md b/docs/contributing/writing-documentation.md new file mode 100644 index 0000000..6d02e15 --- /dev/null +++ b/docs/contributing/writing-documentation.md @@ -0,0 +1,14 @@ +--- +title: Writing Documentation +layout: default +parent: Contributing +nav_order: 4 +--- + +# Writing Documentation + +## TechDocs +Use TechDocs to write thorough documentation explaining the template's purpose, usage, and any other relevant information. This documentation should be clear and concise to assist other contributors and users. + +## Architectural Decision Records (ADRs) +Document all architectural decisions using `mkdocs`. ADRs provide a structured format to capture the rationale behind technical choices, ensuring transparency and clarity. \ No newline at end of file diff --git a/docs/creating-ra/considerations.md b/docs/creating-ra/considerations.md new file mode 100644 index 0000000..27ed57b --- /dev/null +++ b/docs/creating-ra/considerations.md @@ -0,0 +1,14 @@ +--- +title: Considerations While Building RA +layout: default +parent: Tips on Creating RA +nav_order: 3 +--- + +# Considerations While Building Reference Architectures + +1. **Long-Term View**: Building a reference architecture is like developing a city's infrastructure. It's essential to take a long-term view rather than focusing on immediate needs. + - Avoid building for day one. Developers often enhance existing services rather than build new ones. Therefore, focus on creating paths for day two operations, such as integrating additional features, security, and testing. + +2. **Prioritization**: Not everything needs a reference architecture. Prioritize tasks that will have the most significant impact. + - Interact with developers to understand their critical tasks and monitor recent deployments to identify processes that need addressing. Focusing on these will yield the highest impact and ROI. \ No newline at end of file diff --git a/docs/creating-ra/index.md b/docs/creating-ra/index.md new file mode 100644 index 0000000..7ca4b8f --- /dev/null +++ b/docs/creating-ra/index.md @@ -0,0 +1,14 @@ +--- +title: Tips on Creating RA +layout: default +nav_order: 4 +description: "Tips on Creating Reference Architectures" +permalink: /tips-on-creating-ra +has_children: true +--- + +# Tips on Creating Reference Architectures + +This section provides guidance on creating effective reference architectures. It covers the intent-based creation approach, steps to follow, and important considerations to keep in mind during the process. + +Before creating a reference architecture, it's crucial to understand the development process completely. This includes knowing the tools involved, all necessary processes, and the subsequent steps. \ No newline at end of file diff --git a/docs/creating-ra/intent-based-creation.md b/docs/creating-ra/intent-based-creation.md new file mode 100644 index 0000000..e81d8be --- /dev/null +++ b/docs/creating-ra/intent-based-creation.md @@ -0,0 +1,18 @@ +--- +title: Intent-Based Creation +layout: default +parent: Tips on Creating RA +nav_order: 1 +--- + + +# Intent-Based Creation + +The "intent-based" approach involves articulating the intention in a structured format from a developer's point of view: + +"I want to [verb][adjective][noun]" + +For example: +"I want to deploy a scalable Node.js, MongoDB application on Kubernetes." + +This intent-based statement precisely articulates the objective, desired outcome, and specific technologies for deploying a scalable web application. It's a foundational step towards outlining a standardized reference architecture. \ No newline at end of file diff --git a/docs/creating-ra/steps.md b/docs/creating-ra/steps.md new file mode 100644 index 0000000..4ec12d3 --- /dev/null +++ b/docs/creating-ra/steps.md @@ -0,0 +1,24 @@ +--- +title: Steps to Create RA +layout: default +parent: Tips on Creating RA +nav_order: 2 +--- + +# Steps to Create Reference Architecture + +Steps to creating RA + +1. **Define Goals**: Understand the end goal of your reference architecture. What do you want to achieve? + +2. **Choose Your Tools**: Engage with your end users (developers) to understand the tools they use daily. + +3. **Research Best Practices**: Research industry standards and best practices for using the chosen tools and processes. + +4. **Create a Prototype**: Using the gathered tools and best practices, create an initial version of the reference architecture. + +5. **Documentation**: Create detailed documentation of each step, tool usage, configuration settings, and best practices. + +6. **Get Feedback and Iterate**: Share the prototype and documentation with your developers to gather feedback. + +7. **Deploy to Product Central**: Once ready, deploy the reference architecture to Product Central as a template or guided walkthrough. \ No newline at end of file diff --git a/docs/home/documentation.md b/docs/home/documentation.md new file mode 100644 index 0000000..499835c --- /dev/null +++ b/docs/home/documentation.md @@ -0,0 +1,14 @@ +--- +title: Product Central Documentation +layout: home +nav_order: 3 +description: "Product Central Documentation" +parent: Home +--- + +# Product Central Documentation + +Documentation is key to understanding and effectively using our templates. Each template comes with: + +- **TechDocs**: Detailed technical documentation explaining the template’s purpose, setup, and usage. +- **ADRs**: Architectural Decision Records that capture the reasoning behind key technical decisions. \ No newline at end of file diff --git a/docs/home/introduction.md b/docs/home/introduction.md new file mode 100644 index 0000000..6bbc3fc --- /dev/null +++ b/docs/home/introduction.md @@ -0,0 +1,55 @@ +--- +title: Introduction +layout: home +nav_order: 1 +description: "Introduction to Product Central" +parent: Home +--- + +# Introduction + +Product Central aims to standardize and simplify the development process by providing reference architecture templates that embody best practices and scalable solutions. These templates help teams accelerate their projects and ensure they are built on robust, well-defined foundations. + +### Reference Architecture + +Reference architecture serves as a blueprint for designing and implementing systems. It encapsulates best practices, guidelines, and standardized components to create a robust and scalable architecture. + +#### Benefits of Reference Architecture: + +- **Guidance**: Provides clear guidelines on the structure and components of the system. +- **Reusability**: Components and patterns can be reused across different projects, saving time and effort. +- **Quality**: Ensures that the system adheres to best practices and industry standards. + +### Benefits of Using Product Central Templates + +- **Consistency**: Maintain a consistent structure across projects. +- **Best Practices**: Leverage industry best practices embedded in the templates. +- **Time-Saving**: Reduce development time with ready-to-use components. +- **Scalability**: Build scalable and maintainable applications. + +## Templates + +Our repository includes a variety of templates tailored for different use cases. Each template is thoroughly documented to help you understand its purpose and how to integrate it into your projects. + +Explore our templates: + +- **[AWS Fullstack App](https://github.com/99x/product-central-architectures/tree/main/architectures/github/aws-fullstack-app)** +- **[99x Design System](https://github.com/99x/product-central-architectures/tree/main/architectures/github/99x-design-system)** +- **[Product Central on AWS](https://github.com/99x/product-central-architectures/tree/main/architectures/github/pdp-aws)** + +## Documentation + +Documentation is key to understanding and effectively using our templates. Each template comes with: + +- **TechDocs**: Detailed technical documentation explaining the template’s purpose, setup, and usage. +- **ADRs**: Architectural Decision Records that capture the reasoning behind key technical decisions. + +## Support + +Need help? Reach out to the Product Central Team and we are happy to assist you! + +## Contact Us + +For any queries or further assistance, please reach out to the repository maintainers or join our community discussions on GitHub. + +Thank you for being a part of the Product Central community. Together, we can build better, faster, and more scalable solutions. diff --git a/docs/home/product-central-template.md b/docs/home/product-central-template.md new file mode 100644 index 0000000..38de06b --- /dev/null +++ b/docs/home/product-central-template.md @@ -0,0 +1,34 @@ +--- +title: Product Central Template +layout: home +nav_order: 2 +description: "Product Central Template" +parent: Home +--- + +# Product Central Template + +Our repository includes a variety of templates tailored for different use cases. Each template is thoroughly documented to help you understand its purpose and how to integrate it into your projects. + +Explore our templates: + +- **[AWS Fullstack App](https://github.com/99x/product-central-architectures/tree/main/architectures/github/aws-fullstack-app)** +- **[99x Design System](https://github.com/99x/product-central-architectures/tree/main/architectures/github/99x-design-system)** +- **[Product Central on AWS](https://github.com/99x/product-central-architectures/tree/main/architectures/github/pdp-aws)** + +## Documentation + +Documentation is key to understanding and effectively using our templates. Each template comes with: + +- **TechDocs**: Detailed technical documentation explaining the template’s purpose, setup, and usage. +- **ADRs**: Architectural Decision Records that capture the reasoning behind key technical decisions. + +## Support + +Need help? Reach out to the Product Central Team and we are happy to assist you! + +## Contact Us + +For any queries or further assistance, please reach out to the repository maintainers or join our community discussions on GitHub. + +Thank you for being a part of the Product Central community. Together, we can build better, faster, and more scalable solutions. diff --git a/docs/home/quick-start.md b/docs/home/quick-start.md new file mode 100644 index 0000000..0e1a929 --- /dev/null +++ b/docs/home/quick-start.md @@ -0,0 +1,78 @@ +--- +title: Quick Start +layout: home +nav_order: 4 +description: "Quick Start" +parent: Home +--- + +# Quick Start + +This guide will walk you through the process of setting up and running the application. Product Central is designed to streamline your development workflow by integrating with GitHub and providing a powerful interface for managing your projects. Follow these steps to get up and running quickly. + +### Prerequisites + +Before you begin, ensure you have the following prerequisites installed: + +- Docker (v20.10.0 or later) +- Docker Compose (v2.10.0 or later) +- PostgreSQL (v14.0 or later) +- Node.js (v18.12.0 or later) +- npm (v6.14.13 or later) + +### Running the Application + +**1. Run the container** + +```yaml +docker run -it -p 7007:7007 \ + -e APP_URL= \ + -e POSTGRES_HOST= \ + -e POSTGRES_PORT= \ + -e POSTGRES_USER= \ + -e POSTGRES_PASSWORD= \ + -e GITHUB_TOKEN= \ + -e AUTH_GITHUB_CLIENT_ID= \ + -e AUTH_GITHUB_CLIENT_SECRET= \ + 99xproductcentral/product-central: +``` + +
+ +**2. Environment Variables Explained** + +* `APP_URL`: The URL of your application. For instance, `http://localhost:7007`. +* `POSTGRES_HOST`: The hostname of the PostgreSQL database. +* `POSTGRES_PORT`: The port of the PostgreSQL database (default: 5432). +* `POSTGRES_USER`: The username for the PostgreSQL database. +* `POSTGRES_PASSWORD`: The password for the PostgreSQL database. +* `GITHUB_TOKEN`: A GitHub Personal Access Token. +* `AUTH_GITHUB_CLIENT_ID`: The GitHub client ID for authentication. +* `AUTH_GITHUB_CLIENT_SECRET`: The GitHub client secret for authentication. + +
+ +### Authentication and Integration + +**1. Integration With Github:** + +* **Personal Access Token (PAT):** + * Go to your GitHub settings ([https://github.com/settings/tokens](https://github.com/settings/tokens)). + * Click on "Generate new token" and select "Generate new token (classic)". + * Give your token a descriptive name and select these scopes: + * `repo` + * `read:org` + * `user` + * Click "Generate token". + +**2. Authentication:** + +* **GitHub Client ID and Client Secret:** + * Go to your Github OAuth Apps settings ([https://github.com/settings/developers](https://github.com/settings/developers)). + * Click on "New OAuth App". + * During creation, specify the necessary permissions and callback URLs. + * Application name: The name of your application. + * Homepage URL: The URL of your application. For instance, `http://localhost:3000`. + * Application description: A brief description of your application. + * Authorization callback URL: The URL to redirect to after the user authorizes the app. For instance, `http://localhost:3000/api/auth/callback/github`. + * Once created, find the client ID and `generate new` client secret from the app settings. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..c6c7519 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,24 @@ +--- +title: Home +layout: home +nav_order: 1 +description: "Collection of Software Architectures / Golden Path for Product Central bundled with TechDocs and ADR." +permalink: / +has_children: true +--- + +## Introduction + +Welcome to the Product Central Architecture documentation. This space is designed to provide comprehensive guidance and resources for contributors and users of Product Central's reference architecture templates. + +## Overview + +Product Central provides a set of reference architecture templates to help developers and teams streamline the development and deployment of their applications. These templates offer best practices, standardized structures, and ready-to-use components, ensuring consistency and quality across projects. + +## Key Sections + +1. **Introduction**: Learn about Product Central, its mission, and the benefits of using reference architecture templates. +2. **Contributing**: Detailed guidelines on how to contribute to the repository, including forking, cloning, creating content, and raising pull requests. +3. **Templates**: Explore the various templates available, their use cases, and detailed documentation. +4. **Documentation**: Access comprehensive documentation on each template, including TechDocs and Architectural Decision Records (ADRs). +5. **Support**: Find resources for troubleshooting, support channels, and contact information for repository maintainers. \ No newline at end of file diff --git a/docs/maturity-model/clone-and-forget.md b/docs/maturity-model/clone-and-forget.md new file mode 100644 index 0000000..b8e6116 --- /dev/null +++ b/docs/maturity-model/clone-and-forget.md @@ -0,0 +1,10 @@ +--- +title: Clone and Forget +layout: default +parent: RA Maturity Model +nav_order: 3 +--- + +# Clone and Forget + +At this level, templates exist for all Reference Architecture artifacts, such as repository templates, pipeline templates, and templated manifests. Developers clone and run these templates with specific parameters during onboarding to obtain ready-to-use artifacts. From then on, the development team owns these artifacts, leading to a bifurcation between the evolution of the Reference Architecture templates and the specific instance. As divergence increases, it becomes harder to integrate updates from the Reference Architecture templates, often requiring manual merges. Early adopters experience the most significant drifts. \ No newline at end of file diff --git a/docs/maturity-model/index.md b/docs/maturity-model/index.md new file mode 100644 index 0000000..75c5d4e --- /dev/null +++ b/docs/maturity-model/index.md @@ -0,0 +1,18 @@ +--- +title: RA Maturity Model +layout: default +nav_order: 3 +description: "Reference Architecture Maturity Model" +permalink: /maturity-model +has_children: true +--- + +# Reference Architecture Maturity Model + +This section describes the three levels of maturity for Reference Architectures: + +1. No Reference Architecture +2. Clone and Forget +3. Reference Architecture as Product + +Each level is explained in detail in its respective subsection. \ No newline at end of file diff --git a/docs/maturity-model/no-reference-architecture.md b/docs/maturity-model/no-reference-architecture.md new file mode 100644 index 0000000..9a68b34 --- /dev/null +++ b/docs/maturity-model/no-reference-architecture.md @@ -0,0 +1,19 @@ +--- +title: No Reference Architecture +layout: default +parent: RA Maturity Model +nav_order: 3 +--- + +# No Reference Architecture + +At this level of maturity, the platform is architected enough to build and run applications, but no Reference Architecture exists. This level is significant since the ability to build and run applications is a prerequisite for creating Reference Architectures. + +## Key Capabilities + +- **Onboarding Teams and Applications**: A method for onboarding teams and applications with minimal additional processes (preferably one form to submit). +- **CI Pipeline Creation**: A tool for creating and running CI pipelines, empowering developers to write and run their own. +- **Application Deployment (CD)**: Ideally, a GitOps-based approach that allows developers to create their own manifests with the platform consuming and reconciling them. +- **Provisioning Credentials**: A way to provision credentials for integrations like version control systems, image registries, static code analysis tools, vulnerability scanning tools, databases, messaging, caches, and remote service invocations. + +At this level, every development team must figure out how to write the pipeline and deployment manifests, leading to duplication of efforts and inconsistencies. However, this helps establish patterns for later use. \ No newline at end of file diff --git a/docs/maturity-model/reference-architecture-as-product.md b/docs/maturity-model/reference-architecture-as-product.md new file mode 100644 index 0000000..5982da7 --- /dev/null +++ b/docs/maturity-model/reference-architecture-as-product.md @@ -0,0 +1,10 @@ +--- +title: Reference Architecture as Product +layout: default +parent: RA Maturity Model +nav_order: 3 +--- + +# Reference Architecture as Product + +At this maturity level, Reference Architectures are treated as products with releases, new features, and bug fixes. Backward-incompatible releases may occur, requiring specific files within the code repository. Developer teams using a particular Reference Architecture can adopt new releases when feasible. Dedicated Platform teams maintain Reference Architectures, create documentation, release notes, and assist developer teams in adoption. Establishing feedback loops with the developer community is crucial for evolving Reference Architectures based on ongoing requirements. diff --git a/docs/writing-guides/adr-structure.md b/docs/writing-guides/adr-structure.md new file mode 100644 index 0000000..f46b9fc --- /dev/null +++ b/docs/writing-guides/adr-structure.md @@ -0,0 +1,24 @@ +--- +title: ADR Structure +layout: default +parent: Writing TechDocs and ADRs Efficiently +nav_order: 2 +--- + +# ADR Structure + +When writing Architectural Decision Records (ADRs), consider including the following sections: + +1. **Title**: A short phrase describing the decision. + +2. **Status**: The current status of the decision (e.g., proposed, accepted, rejected, deprecated, superseded). + +3. **Context**: The factors that influenced the decision and any constraints that were present. + +4. **Decision**: The change that we're proposing or have agreed to implement. + +5. **Consequences**: The resulting context after applying the decision, including both positive and negative consequences. + +6. **Alternatives Considered**: Other options that were considered and why they were not chosen. + +7. **References**: Any relevant sources of information that influenced the decision. \ No newline at end of file diff --git a/docs/writing-guides/index.md b/docs/writing-guides/index.md new file mode 100644 index 0000000..21fa619 --- /dev/null +++ b/docs/writing-guides/index.md @@ -0,0 +1,10 @@ +--- +title: Writing TechDocs and ADRs Efficiently +layout: default +nav_order: 5 +has_children: true +--- + +# Writing TechDocs and ADRs Efficiently + +This section offers guidelines and best practices for writing effective Technical Documentation (TechDocs) and Architectural Decision Records (ADRs). It includes information on structure, content, and tips for efficient writing. \ No newline at end of file diff --git a/docs/writing-guides/techdocs-structure.md b/docs/writing-guides/techdocs-structure.md new file mode 100644 index 0000000..dbeb5ec --- /dev/null +++ b/docs/writing-guides/techdocs-structure.md @@ -0,0 +1,26 @@ +--- +title: TechDocs Structure +layout: default +parent: Writing TechDocs and ADRs Efficiently +nav_order: 1 +--- + +# TechDocs Structure + +When writing TechDocs, consider including the following sections: + +1. **Introduction**: Introduce the main topic, providing a brief overview and setting the context. + +2. **Scenario Description**: Describe the specific scenario or problem that the doc addresses. + +3. **Architecture Overview**: Provide a high-level view of the architecture, including key components and their interactions. + +4. **Detailed Architecture**: Dive into the specifics of each component, explaining its role and how it fits into the overall architecture. + +5. **Implementation Steps**: Outline the step-by-step process to implement the architecture, including setup and configuration details. + +6. **Best Practices**: Share tips and best practices to ensure the solution is robust, secure, and scalable. + +7. **Cost Considerations**: Discuss the cost implications of the solution and provide strategies for cost optimization. + +8. **Conclusion**: Summarize the main points of the doc and provide final thoughts or next steps. \ No newline at end of file diff --git a/docs/writing-guides/writing-tips.md b/docs/writing-guides/writing-tips.md new file mode 100644 index 0000000..aea7e61 --- /dev/null +++ b/docs/writing-guides/writing-tips.md @@ -0,0 +1,27 @@ +--- +title: Writing Tips +layout: default +parent: Writing TechDocs and ADRs Efficiently +nav_order: 3 +--- + +# Tips for Efficient Writing + +When writing TechDocs or ADRs, keep these tips in mind: + +- **Be Concise**: Keep sentences and paragraphs short and to the point. +- **Use Subheadings**: Break down content into sections with clear subheadings for easier navigation. +- **Include Visuals**: Use diagrams, screenshots, or code snippets to illustrate complex concepts. +- **Stay Focused**: Stick to the topic and avoid unnecessary tangents. +- **Review and Edit**: Proofread your doc for clarity, coherence, and grammatical accuracy. +- **Use Examples**: Provide concrete examples to illustrate abstract concepts. +- **Consider Your Audience**: Write with your intended readers in mind, adjusting the level of technical detail as necessary. +- **Update Regularly**: Keep your documentation up-to-date as the architecture or decisions evolve. + +By following these tips, you can write efficient, well-organized docs that effectively communicate your message. + +### References + +1. https://learn.microsoft.com/en-us/azure/architecture/browse +2. https://aws.amazon.com/architecture/reference-architecture-diagrams +3. https://cloud.google.com/blog/products/application-development/13-popular-application-architectures-for-google-cloud \ No newline at end of file