Skip to content

Add comprehensive architecture documentation#60

Open
NikolayS wants to merge 1 commit intomainfrom
claude/add-architecture-diagrams-wT9ne
Open

Add comprehensive architecture documentation#60
NikolayS wants to merge 1 commit intomainfrom
claude/add-architecture-diagrams-wT9ne

Conversation

@NikolayS
Copy link
Copy Markdown
Contributor

@NikolayS NikolayS commented May 1, 2026

Summary

This PR adds a new ARCHITECTURE.md file that documents the postgresai system design through two complementary views: a high-level data-flow diagram and a detailed component diagram. Both diagrams use Mermaid syntax for easy rendering on GitHub/GitLab.

Key Changes

  • High-level view: Illustrates the main actors (User, CLI, Target PostgreSQL, Monitoring Stack, Cloud), the two storage backends (Postgres sink and VictoriaMetrics), and how data flows between them
  • Component view: Expands the system to show individual containers/services including:
    • User-side tools (CLI, AI IDE, MCP server)
    • Target databases (PostgreSQL 14–18 with extensions)
    • Monitoring stack services (pgwatch, Grafana, Flask backend, reporter, self-monitoring)
    • Cloud platform (console.postgres.ai)
  • Component cheat sheet: Reference table explaining the role of each major component
  • Storage rationale: Explains why both VictoriaMetrics (time-series) and Postgres sink (structured rows) are used

Notable Details

  • Both diagrams use Mermaid flowchart syntax with color-coded styling for different system layers (storage, cloud, user, targets)
  • Documentation emphasizes key architectural decisions: dual-storage approach, optional cloud integration, and the CLI as the unified entry point
  • Includes connection details (protocols, data types) on diagram edges for clarity
  • Covers both express checkup (one-shot) and full monitoring (continuous) modes

https://claude.ai/code/session_015msHQaT5kpRiSCqL6frw7i

Two Mermaid diagrams: a high-level data-flow view showing the two
storage backends (sink-postgres and VictoriaMetrics), and a detailed
component view of the monitoring stack, CLI, MCP, and cloud surfaces.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants