Systems Architecture

Core Objective

Analyze lifecycle documentation and repository structure to generate a high-level system architecture document. The goal is to provide a "bird's-eye view" that identifies major logic centers, dependencies, and core technologies for new engineers.

Guardrails

• Derive architecture from lifecycle docs and source evidence, not guesses.
• Label uncertain ownership, boundaries, or data flow as assumptions.
• Keep the diagram to major actors only. Do not model every file or helper.
• Do not recommend refactors unless explicitly asked.

---

Mandated Output Structure

1. System Overview Diagram (Mermaid)

• Scale: 5–10 major actors (heavy logic components).
• Visuals: Labeled arrows for data/control flow; subgroups for deployment boundaries (containers, VMs, external services).
• Detail: Annotate with primary technologies or protocols.

2. Component Catalog

A table detailing major actors:

| Component Name | Technology/Framework | Primary Responsibility | Key Files (2-3) | Heavy Logic Description | | --- | --- | --- | --- | --- | | Example: API Gateway | Node.js/Express | Auth and Routing | index.js, auth.js | Token lifecycle/validation |

3. Technology Stack Reference

Categorize keys technologies by layer:

• UI Layer: Frameworks and libraries.
• State/Logic Layer: Management patterns.
• Service/API Layer: Communication frameworks.
• Data Layer: Persistence and caching.
• External Dependencies: Third-party APIs and services.

4. Integration Points

Define communication methods:

• Protocol: (e.g., HTTP, IPC, WebSocket).
• Data Format: (e.g., JSON, Protobuf).
• Nature: Synchronous vs. Asynchronous.

5. Navigation Guide

Explicit pointers for onboarding:

• User Interactions: Reference specific lifecycle docs.
• Data Flow: Identify the starting component.
• Business Logic: Identify the primary logic engine.

---

Selection Guidelines (Filtering)

To maintain clarity and prioritize impact, follow these constraints:

• Major Actors Only: Include only components where significant logic resides. If its removal would require a major rewrite, include it.
• Exclusions: Omit simple pass-throughs, thin wrappers, utility libraries, pure UI components, and configuration-only files.
• Prioritization: Limit to a maximum of 10 major components.

---

---

> Install: `npx skills add ChristopherAlphonse/calphonse-skills --skill systems-architecture`

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ChristopherAlphonse
• Source: ChristopherAlphonse/calphonse-skills
• License: MIT
• Homepage: https://www.skills.sh/christopheralphonse/calphonse-skills

Install and usage instructions live in the source repository linked above.