joggrdocs · zrosenbauer · Apr 2, 2025
@@ -121,6 +121,7 @@ dist
 
 # Stores VSCode versions used for testing VSCode extensions
 .vscode-test
+.vscode
 
 # yarn v2
 .yarn/cache

@@ -1,28 +1,26 @@
 <!--  
-📝 Usage:  
-- Replace {{company}} with the name of your company.
-- Replace {{reason}} with the reason for the third-party service.
-- Update links and remove unnecessary sections.
-- Customize as needed.  
+�� Usage:  
+- Replace all {{placeholders}} with your organization's content
+- Update links and remove unnecessary sections
+- Customize as needed 
 
 Happy documenting! 🚀  
 -->
 
-# 📊 System Overview
+# 🏗️ Service Architecture
 
-This document provides you with an overview of the services (applications), vendors and other assets that make up the our platform and how they interact.
+This document provides an overview of the services, vendors, and assets that make up the {{ app }} platform and how they interact.
 
-## Services
+## 🎯 Core Services
 
-There are four primary services that make up our platform.
-| Service                     | Description                                                                                                                                  | Endpoint               |
-|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|------------------------|
-| 🔌 **API**                  | The {{company}} **API** is the main API for our Platform. It is responsible for all of the business logic and data storage for the Platform. | `https://api.acme.io`  |
-| 🌐 **Web**                  | The {{company}} **Web** consists of a React-based application that is a SPA.                                                                 | `https://app.acme.io`  |
-| ⚙ **Server**                | The {{company}} **Server** is a Fastify based API that serves the **Web** to the client.                                                     | `https://app.acme.io`  |
-| 🔗 **Third-Party Service**  | The {{company}} **Third-Party Service** is a proxy API for {{reason}}. It is responsible for {{reason}}.                                     | `https://app.acme.io`  |
+| Service | Description | Endpoint | Owner |
+|---------|-------------|----------|-------|
+| 🔌 **API** | The {{ app }} **API** is the main API for our Platform. It is responsible for all of the business logic and data storage for the Platform. | `{{ api-endpoint }}` | {{ api-owner }} |
+| 🌐 **Web** | The {{ app }} **Web** consists of a React-based application that is a SPA. | `{{ web-endpoint }}` | {{ web-owner }} |
+| ⚙️ **Server** | The {{ app }} **Server** is a Fastify based API that serves the **Web** to the client. | `{{ server-endpoint }}` | {{ server-owner }} |
+| 🔗 **Third-Party Service** | The {{ app }} **Third-Party Service** is a proxy API for {{ third-party-reason }}. | `{{ third-party-endpoint }}` | {{ third-party-owner }} |
 
-## System Diagram
+## 🔄 System Flow
 
 ```mermaid
 %%{init: {
@@ -39,10 +37,10 @@ There are four primary services that make up our platform.
 
 flowchart TD
     %% Title
-    title["Acme Inc. Service Architecture"]
+    title["{{ company-name }} Service Architecture"]
     style title fill:none,stroke:none,color:#333,font-weight:bold
 
-    %% Core Services - using round shapes with parentheses
+    %% Core Services
     web("🌐 Web Client")
     style web fill:#7b1fa2,color:white,stroke:#5d1777,stroke-width:2px
 
@@ -55,31 +53,31 @@ flowchart TD
     third-party("🐙 Third-Party Proxy")
     style third-party fill:#00897b,color:white,stroke:#005b4f,stroke-width:2px
 
-    %% AWS Services
-    database[("🐘 MicrosoftSQL")]
+    %% Database Services
+    database[("🐘 {{ database-name }}")]
     style database fill:#0064a5,color:white,stroke:#004c7f,stroke-width:2px
 
     bucket("🪣 Storage Bucket")
     style bucket fill:#0064a5,color:white,stroke:#004c7f,stroke-width:2px
 
     %% Vendor Services
-    Okta("🔐 Okta.com")
-    style Okta fill:#f57c00,color:white,stroke:#bc5100,stroke-width:2px
+    auth("🔐 {{ auth-provider }}")
+    style auth fill:#f57c00,color:white,stroke:#bc5100,stroke-width:2px
 
-    thirdpartyapi("🔌 thirdparty.com")
+    thirdpartyapi("🔌 {{ third-party-api }}")
     style thirdpartyapi fill:#f57c00,color:white,stroke:#bc5100,stroke-width:2px
 
-    %% Connections with descriptive labels
+    %% Connections
     web -- "Serves UI" --> server
     web <-- "API Requests" --> api
     web <-- "CDN Assets" --> api
     api <-- "Static Assets" --> bucket
-    api <-- "Auth" --> Okta
-    web <-- "Login" --> Okta
+    api <-- "Auth" --> auth
+    web <-- "Login" --> auth
     third-party <-- "Proxy Requests" --> thirdpartyapi
     api -- "Database Queries" --> database
 
-    %% Subgraph containers
+    %% Network Groups
     subgraph vpc ["🛜 VPC Network"]
         direction TB
         api -- "Internal API Calls" --> third-party
@@ -88,20 +86,53 @@ flowchart TD
     end
     style vpc fill:#e3f2fd,color:#0d47a1,stroke:#0d47a1,stroke-width:3px,stroke-dasharray:5
 
-    subgraph gcp ["💽 AWS Managed Services"]
+    subgraph cloud ["💽 {{ cloud-provider }} Managed Services"]
         direction TB
         database
         bucket
     end
-    style gcp fill:#e1f5fe,color:#01579b,stroke:#01579b,stroke-width:3px,stroke-dasharray:5
+    style cloud fill:#e1f5fe,color:#01579b,stroke:#01579b,stroke-width:3px,stroke-dasharray:5
 
     subgraph vendors ["🏪 External Vendors"]
         direction TB
         thirdpartyapi
-        Okta
+        auth
     end
     style vendors fill:#fff3e0,color:#e65100,stroke:#e65100,stroke-width:3px,stroke-dasharray:5
 
     %% Global link styling
     linkStyle default stroke-width:2px,stroke:#666
 ```
+
+## 🔒 Security
+
+### Authentication
+- {{ auth-provider }} for user authentication
+- {{ auth-flow-description }}
+
+### Authorization
+- {{ authorization-model }}
+- {{ role-descriptions }}
+
+## 📊 Monitoring & Observability
+
+### Metrics
+- {{ metric-1 }}
+- {{ metric-2 }}
+- {{ metric-3 }}
+
+### Logging
+- {{ logging-tool }}
+- {{ log-retention-policy }}
+
+## 🔍 Related Documents
+
+- [Infrastructure Overview](./infrastructure.md)
+- [Security Standards](./security.md)
+- [Deployment Process](./deployment.md)
+
+## 📚 Additional Resources
+
+- [{{ app }} Architecture Decisions](../architecture/decisions.md)
+- [Service Dependencies](./dependencies.md)
+- [Performance Guidelines](./performance.md)
@@ -1,6 +1,6 @@
 <!--  
-📝 Usage:  
-- Replace any {{placeholders}} with your own content
+�� Usage:  
+- Replace all {{placeholders}} with your organization's content
 - Update links and remove unnecessary sections
 - Customize as needed 
 
@@ -9,23 +9,20 @@ Happy documenting! 🚀
 
 # 📝 Contribution Guidelines
 
-Welcome to our codebase! To keep things smooth and **less chaotic than a merge conflict on a Friday afternoon**, please follow these contribution guidelines.
+Welcome to the {{ app }} codebase! This guide outlines our contribution process and standards to maintain code quality and collaboration.
 
-***
+## 🎯 Development Workflow
 
-## 🔀 Branching Strategy
+### Branching Strategy
 
-We follow **Trunk-Based Development**.
+We follow **Trunk-Based Development** with the following branches:
 
-### **Trunk-Based Development Example:**
-
-* **Main (**`main`**)** – Always production-ready. All changes merge directly here after review.
-
-* **Feature Branches (**`feature/your-feature`**)** – Short-lived branches created from `main`, merged back ASAP.
-
-* **Hotfixes (**`hotfix/critical-bug`**)** – Branch from `main` for urgent fixes, merge quickly.
-
-* **Releases** – We tag releases from `main`, no separate release branches.
+| Branch Type | Pattern | Description | Lifecycle |
+|-------------|---------|-------------|-----------|
+| **Main** | `main` | Production-ready code | Long-lived |
+| **Feature** | `feature/{{ feature-name }}` | New features | Short-lived |
+| **Hotfix** | `hotfix/{{ issue-description }}` | Critical fixes | Very short-lived |
+| **Release** | `v{{ version }}` | Release tags | Permanent |
 
 ```mermaid
 gitGraph
@@ -45,53 +42,132 @@ gitGraph
     commit id: "Continuous Integration Build"
 ```
 
-***
-
-## ✅ Code Review Process
-
-* **Who Approves PRs?** → At least **\[#]** approvals required before merging. No self-merges.
+## 🔍 Code Review Process
+
+### Review Requirements
+
+- **Approvals**: {{ required-approvals }} approvals required
+- **Self-Review**: No self-merges allowed
+- **Review Style**: Constructive feedback with actionable items
+- **Documentation**: Update relevant documentation
+
+### Review Guidelines
+
+1. **Code Quality**
+   - Follow coding standards
+   - Include tests
+   - Update documentation
+   - No linting errors
+
+2. **PR Description**
+   - Clear title
+   - Detailed description
+   - Screenshots/GIFs when relevant
+   - Link to related issues
+
+3. **Commit Messages**
+   ```bash
+   # Format
+   type(scope): description (#issue-number)
+
+   # Example
+   fix(auth): resolve login redirect issue (#123)
+   ```
+
+## ⏳ Pull Request Standards
+
+### PR Requirements
+
+| Requirement | Description |
+|-------------|-------------|
+| **Size** | Maximum {{ max-files }} files per PR |
+| **Scope** | One feature/fix per PR |
+| **Tests** | All tests must pass |
+| **Documentation** | Update relevant docs |
+
+### PR Template
+
+```markdown
+## Description
+{{ pr-description }}
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+
+## Testing
+- [ ] Unit tests added/updated
+- [ ] Integration tests added/updated
+- [ ] Manual testing completed
+
+## Documentation
+- [ ] README updated
+- [ ] API docs updated
+- [ ] Release notes updated
+```
 
-* **Review Style** → Keep it constructive, don’t just say *“LGTM”*, and **leave actionable feedback**.
+## ⚡ Response Times
 
-* **The GIF Rule** → It’s an unwritten law that every PR **must** contain at least one GIF (or equivalent meme).
+### Review SLAs
 
-***
+| Action | Timeframe | Escalation |
+|--------|-----------|------------|
+| Initial Review | {{ review-sla }} hours | @{{ reviewer-role }} |
+| Follow-up | {{ followup-sla }} hours | @{{ team-lead }} |
+| Merge | {{ merge-sla }} hours | @{{ tech-lead }} |
 
-## 📌 PR Standards
+## 🛠️ Development Tools
 
-A **good PR** should be:
+### Required Tools
 
-* **Small & Focused** → Aim for **\[#] files max** per PR.
+| Tool | Version | Usage |
+|------|---------|-------|
+| {{ tool-1 }} | {{ version-1 }} | {{ usage-1 }} |
+| {{ tool-2 }} | {{ version-2 }} | {{ usage-2 }} |
+| {{ tool-3 }} | {{ version-3 }} | {{ usage-3 }} |
 
-* **Descriptive** → PR title and description should **explain the *why* behind the change**, not just *“fixed stuff”*.
+### Code Quality Tools
 
-* **Linked to Issues/Tickets** → Reference relevant issues (e.g., `Closes #123`).
+```bash
+# Format code
+npm run format
 
-* **Clear Commits** → Use meaningful commit messages:
+# Run linter
+npm run lint
 
-```shell
-git commit -m "Fix user authentication bug (#123)"
+# Run tests
+npm test
 ```
 
-***
-
-## ⏳ PR SLAs
+## 🚀 Getting Started
 
-* **Time to Review** → PRs should be reviewed within **\[#] hours** of submission.
+1. **Fork the Repository**
+   ```bash
+   git clone {{ repository-url }}
+   cd {{ repository-name }}
+   ```
 
-* **Merging PRs** → If a PR sits unreviewed for **\[#] days**, gently **@mention reviewers**.
+2. **Set Up Development Environment**
+   ```bash
+   npm install
+   npm run setup
+   ```
 
-* **No PR Left Behind** → Every PR gets reviewed. If yours is stuck, **poke the team (politely)**.
+3. **Create Feature Branch**
+   ```bash
+   git checkout -b feature/{{ feature-name }}
+   ```
 
-***
+## 🔍 Related Documents
 
-## 🔧 Linting, Formatting & CI/CD
+- [Code Style Guide](../standards/code-style.md)
+- [Testing Standards](../standards/testing.md)
+- [Documentation Standards](../standards/documentation.md)
 
-* **Linting:** We use [ESLint](https://eslint.org/) – no failing lint checks in PRs.
+## 📚 Additional Resources
 
-* **Formatting:** Auto-format before committing. Use:
-
-* **CI/CD Checks:** All PRs **must** pass automated tests before merging. No exceptions.
-
-```shell
-npm run format
+- [{{ app }} Documentation]({{ docs-url }})
+- [API Reference]({{ api-docs-url }})
+- [Architecture Overview](../architecture/overview.md)