Architecture

vasili.protepo.com site architecture

This Praxis artifact documents the public website as an engineering artifact: how the content is authored, how the static site is built, how deployment is controlled, and how the same architecture record is kept visible in GitHub, Diavgeia, and the public site.

Design Principles

Public by default

Architecture, operating choices, and implementation tradeoffs are written where they can be inspected: source control, Diavgeia, and the published site.

Static first

Astro produces static HTML, CSS, JavaScript, and assets. The production surface is intentionally small and easy to host.

Documented decisions

Architecture decision records, design prompts, reference guides, and generated inventory are kept near the code that they explain.

Build once, promote carefully

Local validation, GitHub Actions, UAT deployment, and production promotion are treated as explicit stages instead of ad hoc file copying.

Block Architecture

Runtime requests stay simple while source, documentation, validation, and deployment remain explicit.

Mermaid source

flowchart TB
  visitor[Visitor or crawler] --> publicSite[vasili.protepo.com static site]
  publicSite --> html[Generated HTML]
  publicSite --> css[Bundled CSS]
  publicSite --> assets[Images and static assets]
  publicSite --> seo[SEO, JSON-LD, sitemap, robots, llms.txt]

  author[Vasilis / Codex-assisted workflow] --> source[Git working tree]
  source --> astro[Astro pages and components]
  source --> content[Markdown content collections]
  source --> diavgeia[Diavgeia reference docs]
  source --> prompts[Design prompt ledger]
  source --> tests[Validation and browser checks]

  astro --> build[Astro build]
  content --> build
  assets --> build
  build --> dist[dist static artifact]
  dist --> uat[Bluehost UAT]
  dist --> prod[Bluehost Production]
  source --> github[GitHub repository]
  diavgeia --> github

Change Sequence

The change path separates authoring, validation, UAT review, and production promotion.

Mermaid source

sequenceDiagram
  autonumber
  participant Owner as Owner
  participant Repo as Local repo
  participant Astro as Astro build
  participant GitHub as GitHub
  participant UAT as Bluehost UAT
  participant PRD as Bluehost Production

  Owner->>Repo: Edit page, component, content, or Diavgeia note
  Repo->>Repo: Run validation and targeted browser checks
  Repo->>Astro: npm run build
  Astro-->>Repo: dist static output
  Repo->>GitHub: Commit and push source
  GitHub->>UAT: Build and deploy UAT
  Owner->>UAT: Review production-like result
  GitHub->>PRD: Promote approved artifact

Content and Knowledge Flow

The architecture artifact is both a public Praxis artifact and synchronized project memory.

Mermaid source

flowchart LR
  ideas[Ideas and implementation notes] --> prompts[design-prompts]
  ideas --> adr[Diavgeia ADR]
  ideas --> reference[Diavgeia Reference]
  reference --> architecture[Architecture record]
  architecture --> githubDoc[GitHub-rendered Markdown]
  architecture --> publicPage[Public Praxis page]
  architecture --> diavgeiaVault[Diavgeia knowledge base]

  content[src/content Markdown] --> astroPages[Astro routes]
  data[src/data TypeScript] --> astroPages
  components[src/components Astro] --> astroPages
  astroPages --> publicPage

Deployment Model

Production is reached only after local validation, source push, UAT deployment, and review.

Mermaid source

stateDiagram-v2
  [*] --> LocalDevelopment
  LocalDevelopment --> LocalValidation: tests, checks, screenshots
  LocalValidation --> GitHubSource: commit and push
  GitHubSource --> UATDeployment: GitHub Actions
  UATDeployment --> Review
  Review --> ProductionDeployment: approved promotion
  Review --> LocalDevelopment: fix required
  ProductionDeployment --> [*]

Project Root Inventory

This table explains the directories and files at the repository root. Generated folders such as dist/, .astro/, node_modules/, tmp/, and local environment files are intentionally excluded from source control. Tracked configuration lives under config/; the root .env file is reserved for ignored local overrides and secrets.

Path	Type	Purpose
`.github/`	Directory	GitHub Actions workflows for code inventory, UAT deployment, and production promotion.
`.vscode/`	Directory	Workspace editor settings, recommended extensions, and local tasks.
`config/`	Directory	Local, UAT, PRD, GitHub, and deployment-template configuration files.
`design-prompts/`	Directory	Versioned design prompts, implementation notes, and screenshot evidence for visual evolution.
`Diavgeia/`	Directory	Project knowledge base with configuration reference, architecture records, implementation notes, ADRs, operations guides, release notes, and generated inventory assets.
`Diavgeia/Configuration/`	Directory	Tomcat-style configurable component reference for Astro, content, VNC, analytics, GitHub, and Bluehost.
`Diavgeia/Implementation/`	Directory	Developer-facing implementation documentation, including page notes and reusable component notes.
`Diavgeia/Parking/`	Directory	Parked concepts, unresolved questions, and retained assessment artifacts.
`public/`	Directory	Static assets copied directly into the built site, including images, icons, and PROTEPO assets.
`scripts/`	Directory	Python and Node automation for deployment, validation, SEO, analytics, Diavgeia sync, and inventory generation.
`src/`	Directory	Astro source: pages, layouts, components, content collections, data, styles, analytics, and SEO helpers.
`tests/`	Directory	Python and Playwright-oriented checks for pages, analytics, layout boundaries, and deployment helpers.
`tools/`	Directory	Developer tooling that supports screenshots and design verification workflows.
`config/env.local`	File	Local development environment settings.
`config/env.uat`	File	UAT analytics environment settings.
`config/env.prd`	File	Production analytics environment settings.
`config/deploy.uat.template.env`	File	Local UAT FTP deployment template.
`.gitignore`	File	Excludes dependencies, build output, local environment files, and temporary artifacts.
`.env`	Ignored file	Local-only overrides and secrets copied from a tracked config template when needed.
`astro.config.mjs`	File	Astro configuration for the static site build.
`build-site.bat`	File	Windows wrapper for a production-like local build.
`config/github.uat-prd.json`	File	UAT and PRD GitHub environment, variable, and deployment configuration manifest.
`help.bat`	File	Local command helper for common project operations.
`LOCAL_BUILD`	File	Local build marker used by the site release/version display flow.
`package-lock.json`	File	Locked npm dependency graph for reproducible installs.
`package.json`	File	Node package metadata, dependency declarations, and npm scripts.
`preview-built-site.bat`	File	Windows wrapper for previewing the built static site.
`README.md`	File	Primary GitHub-facing project overview and operations entry point.
`run-site.bat`	File	Windows wrapper for daily local development.
`tsconfig.json`	File	TypeScript configuration used by Astro and local type checks.
`vasili.protepo.com.code-workspace`	File	VS Code workspace definition for this project.

Implementation Choices

Astro static site: keeps hosting simple, fast, and inspectable while still allowing component-based implementation.
Markdown collections: keep Noesis entries, Praxis entries, books, and position papers close to source control.
Diavgeia source tree: keeps project memory, architecture, deployment, analytics, and release knowledge in the same repo.
GitHub as public evidence: exposes both the running site and the source-level architecture record.
Generated inventory: keeps the README and Diavgeia inventory grounded in source-controlled files.
Environment-specific deployment: UAT and production use separate environment variables and FTP targets.