# decimozs/portfolio architecture

> Architecture diagram of the GitHub repository decimozs/portfolio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/decimozs/portfolio
- Repository: https://github.com/decimozs/portfolio

## Overview

1. This repository is a personal portfolio / resume site built as a static Astro application. The rendered output is a small set of content-driven pages rather than a dynamic server app.

2. The top-level architecture is split into:
   - page routes in `src/pages`
   - reusable UI in `src/components`
   - shared page shells in `src/layouts`
   - content data in `src/content`
   - shared utilities/constants in `src/lib`
   - global styling in `src/styles`
   - static public assets in `public`

3. The primary content model is JSON-based and lives under `src/content`:
   - `experience.json`
   - `works.json`
   - `notebooks.json`
   These files are the main data source for the site’s sections and feed the corresponding pages. `src/content.config.ts` defines how Astro treats this content layer.

4. The routes are simple and map directly to the site’s major sections:
   - `src/pages/index.astro` for the home page
   - `src/pages/experience.astro`
   - `src/pages/works.astro`
   - `src/pages/notebooks.astro`
   This indicates a mostly brochure-style information architecture with separate content sections rather than nested application flows.

5. Layout composition is centralized. `src/layouts/Layout.astro` and `src/components/main-layout.astro` act as shared page wrappers, likely handling the global HTML structure, metadata hooks, and overall page chrome. This is the main boundary between page content and site-wide presentation.

6. Navigation and header behavior are isolated into dedicated components:
   - `header.astro`
   - `nav.astro`
   - `hamburger.tsx`
   These form the responsive site navigation layer. The mix of Astro and React/TSX suggests some client-side interactivity is used only where necessary, likely for mobile navigation toggling.

7. The site also includes client-side enhancement components:
   - `smooth-scroll.tsx` for scrolling behavior
   - `posthog.astro` for analytics instrumentation
   - `SEO.astro` plus `src/lib/seo.ts` for metadata generation
   These are cross-cutting concerns attached at the layout level rather than inside individual content pages.

8. Shared helpers in `src/lib` provide application constants and utility functions:
   - `constant.ts`
   - `utils.ts`
   - `seo.ts`
   This keeps page and component logic thin and pushes reusable logic into a central utility boundary.

9. Static assets are served from `public`, including:
   - `resume.pdf`
   - font files
   - `robots.txt`
   - `site.webmanifest`
   - `.assetsignore`
   This indicates the site includes downloadable and SEO-related assets directly in the build output, with no separate asset pipeline.

10. Styling is global-first. `src/styles/globals.css` appears to be the main stylesheet, suggesting the design system is lightweight and site-specific rather than built on a heavy component library.

11. The tooling and runtime stack is modern static-site focused:
   - Astro as the framework
   - TypeScript via `tsconfig.json`
   - Bun lockfile for package management
   - Biome for linting/formatting
   - Lefthook for git hooks
   This points to a small, fast frontend codebase optimized for developer ergonomics.

12. Deployment/runtime infrastructure is Cloudflare-oriented. `wrangler.jsonc` strongly suggests the site is deployed to Cloudflare Workers or Pages. The GitHub Actions workflow in `.github/workflows/ci.yml` likely runs checks/build validation before deployment.

13. From an architecture diagram perspective, the key data flow is:
   content JSON and static assets → Astro pages/components/layouts → static HTML/CSS/JS output → deployment via Cloudflare tooling.  
   Interactive behavior is limited and localized to a few client-side islands rather than the whole app.

14. Overall, this is a content-first portfolio site with clear separation between data, presentation, and cross-cutting concerns, and with minimal backend complexity.

Main entry points: [`src/components/main-layout.astro`](https://github.com/decimozs/portfolio/blob/main/src/components/main-layout.astro) (Main Layout), [`src/pages/index.astro`](https://github.com/decimozs/portfolio/blob/main/src/pages/index.astro) (Home), [`src/layouts/Layout.astro`](https://github.com/decimozs/portfolio/blob/main/src/layouts/Layout.astro) (Layout), [`src/content.config.ts`](https://github.com/decimozs/portfolio/blob/main/src/content.config.ts) (Content Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_src["App Source"]
  node_node_pages_index["Home<br/>route page<br/>[index.astro]"]
  node_node_pages_experience["Experience<br/>route page<br/>[experience.astro]"]
  node_node_pages_works["Works<br/>route page<br/>[works.astro]"]
  node_node_pages_notebooks["Notebooks<br/>route page<br/>[notebooks.astro]"]
  node_node_layout["Layout<br/>shell<br/>[Layout.astro]"]
  node_node_main_layout["Main Layout<br/>page chrome<br/>[main-layout.astro]"]
  node_node_header["Header<br/>navigation chrome<br/>[header.astro]"]
  node_node_nav["Nav<br/>[nav.astro]"]
  node_node_hamburger(("Hamburger<br/>react toggle<br/>[hamburger.tsx]"))
  node_node_smooth_scroll(("Smooth Scroll<br/>client enhancement<br/>[smooth-scroll.tsx]"))
  node_node_seo_component["SEO<br/>meta component<br/>[SEO.astro]"]
  node_node_posthog["PostHog<br/>analytics<br/>[posthog.astro]"]
  node_node_content_config["Content Config<br/>content schema<br/>[content.config.ts]"]
  node_node_content_experience["Experience Data<br/>json content<br/>[experience.json]"]
  node_node_content_works["Works Data<br/>json content<br/>[works.json]"]
  node_node_content_notebooks["Notebook Data<br/>json content<br/>[notebooks.json]"]
  node_node_constants["Constants<br/>shared config<br/>[constant.ts]"]
  node_node_utils["Utils<br/>helpers<br/>[utils.ts]"]
  node_node_seo_lib["SEO Lib<br/>meta helper<br/>[seo.ts]"]
  node_node_styles["Globals<br/>global styles<br/>[globals.css]"]
end

subgraph group_group_public["Static Assets"]
  node_node_resume["Resume PDF<br/>asset<br/>[resume.pdf]"]
  node_node_fonts["Fonts<br/>asset pack"]
  node_node_robotstxt["Robots<br/>seo asset<br/>[robots.txt]"]
  node_node_manifest["Manifest<br/>[site.webmanifest]"]
end

subgraph group_group_tooling["Tooling"]
  node_node_astro_config["Astro Config<br/>framework config<br/>[astro.config.mjs]"]
  node_node_package["Package<br/>project manifest<br/>[package.json]"]
  node_node_tsconfig["TypeScript<br/>compiler config<br/>[tsconfig.json]"]
  node_node_biome["Biome<br/>lint config<br/>[biome.json]"]
  node_node_lefthook["Lefthook<br/>git hooks<br/>[lefthook.yml]"]
end

subgraph group_group_ci["CI / Deploy"]
  node_node_wrangler["Wrangler<br/>deploy config<br/>[wrangler.jsonc]"]
  node_node_ci["CI Workflow<br/>automation<br/>[ci.yml]"]
end

node_node_pages_index -->|"uses"| node_node_layout
node_node_pages_experience -->|"uses"| node_node_layout
node_node_pages_works -->|"uses"| node_node_layout
node_node_pages_notebooks -->|"uses"| node_node_layout
node_node_layout -->|"composes"| node_node_main_layout
node_node_main_layout -->|"includes"| node_node_header
node_node_main_layout -->|"includes"| node_node_nav
node_node_nav -->|"enhanced by"| node_node_hamburger
node_node_main_layout -->|"includes"| node_node_seo_component
node_node_main_layout -->|"includes"| node_node_posthog
node_node_main_layout -->|"enhanced by"| node_node_smooth_scroll
node_node_seo_component -->|"uses"| node_node_seo_lib
node_node_pages_experience -->|"reads"| node_node_content_experience
node_node_pages_works -->|"reads"| node_node_content_works
node_node_pages_notebooks -->|"reads"| node_node_content_notebooks
node_node_content_config -->|"defines"| node_node_content_experience
node_node_content_config -->|"defines"| node_node_content_works
node_node_content_config -->|"defines"| node_node_content_notebooks
node_node_pages_index -->|"uses"| node_node_constants
node_node_pages_index -->|"uses"| node_node_utils
node_node_main_layout -->|"loads"| node_node_styles
node_node_main_layout -->|"serves"| node_node_fonts
node_node_pages_index -->|"links"| node_node_resume
node_node_astro_config -->|"registers"| node_node_content_config
node_node_package -->|"scripts"| node_node_astro_config
node_node_package -->|"uses"| node_node_biome
node_node_package -->|"uses"| node_node_lefthook
node_node_wrangler -->|"deploys"| node_node_astro_config
node_node_ci -->|"runs"| node_node_package
node_node_ci -->|"checks"| node_node_wrangler
node_node_pages_index -->|"uses"| node_node_manifest
node_node_pages_index -->|"uses"| node_node_robotstxt

click node_node_pages_index "https://github.com/decimozs/portfolio/blob/main/src/pages/index.astro"
click node_node_pages_experience "https://github.com/decimozs/portfolio/blob/main/src/pages/experience.astro"
click node_node_pages_works "https://github.com/decimozs/portfolio/blob/main/src/pages/works.astro"
click node_node_pages_notebooks "https://github.com/decimozs/portfolio/blob/main/src/pages/notebooks.astro"
click node_node_layout "https://github.com/decimozs/portfolio/blob/main/src/layouts/Layout.astro"
click node_node_main_layout "https://github.com/decimozs/portfolio/blob/main/src/components/main-layout.astro"
click node_node_header "https://github.com/decimozs/portfolio/blob/main/src/components/header.astro"
click node_node_nav "https://github.com/decimozs/portfolio/blob/main/src/components/nav.astro"
click node_node_hamburger "https://github.com/decimozs/portfolio/blob/main/src/components/hamburger.tsx"
click node_node_smooth_scroll "https://github.com/decimozs/portfolio/blob/main/src/components/smooth-scroll.tsx"
click node_node_seo_component "https://github.com/decimozs/portfolio/blob/main/src/components/SEO.astro"
click node_node_posthog "https://github.com/decimozs/portfolio/blob/main/src/components/posthog.astro"
click node_node_content_config "https://github.com/decimozs/portfolio/blob/main/src/content.config.ts"
click node_node_content_experience "https://github.com/decimozs/portfolio/blob/main/src/content/experience.json"
click node_node_content_works "https://github.com/decimozs/portfolio/blob/main/src/content/works.json"
click node_node_content_notebooks "https://github.com/decimozs/portfolio/blob/main/src/content/notebooks.json"
click node_node_constants "https://github.com/decimozs/portfolio/blob/main/src/lib/constant.ts"
click node_node_utils "https://github.com/decimozs/portfolio/blob/main/src/lib/utils.ts"
click node_node_seo_lib "https://github.com/decimozs/portfolio/blob/main/src/lib/seo.ts"
click node_node_styles "https://github.com/decimozs/portfolio/blob/main/src/styles/globals.css"
click node_node_resume "https://github.com/decimozs/portfolio/blob/main/public/resume.pdf"
click node_node_fonts "https://github.com/decimozs/portfolio/tree/main/public/font"
click node_node_robotstxt "https://github.com/decimozs/portfolio/blob/main/public/robots.txt"
click node_node_manifest "https://github.com/decimozs/portfolio/blob/main/public/site.webmanifest"
click node_node_astro_config "https://github.com/decimozs/portfolio/blob/main/astro.config.mjs"
click node_node_package "https://github.com/decimozs/portfolio/blob/main/package.json"
click node_node_tsconfig "https://github.com/decimozs/portfolio/blob/main/tsconfig.json"
click node_node_biome "https://github.com/decimozs/portfolio/blob/main/biome.json"
click node_node_lefthook "https://github.com/decimozs/portfolio/blob/main/lefthook.yml"
click node_node_wrangler "https://github.com/decimozs/portfolio/blob/main/wrangler.jsonc"
click node_node_ci "https://github.com/decimozs/portfolio/blob/main/.github/workflows/ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_pages_index,node_node_pages_experience,node_node_pages_works,node_node_pages_notebooks,node_node_layout,node_node_main_layout,node_node_header,node_node_nav,node_node_hamburger,node_node_smooth_scroll,node_node_seo_component,node_node_posthog,node_node_content_config,node_node_content_experience,node_node_content_works,node_node_content_notebooks,node_node_constants,node_node_utils,node_node_seo_lib,node_node_styles toneBlue
class node_node_resume,node_node_fonts,node_node_robotstxt,node_node_manifest toneAmber
class node_node_astro_config,node_node_package,node_node_tsconfig,node_node_biome,node_node_lefthook toneMint
class node_node_wrangler,node_node_ci toneRose
```

## Components

### App Source

Astro site code, content, styles, and shared helpers.

- [Home](https://github.com/decimozs/portfolio/blob/main/src/pages/index.astro): route page · Landing page route for the portfolio home. · `src/pages/index.astro`
- [Experience](https://github.com/decimozs/portfolio/blob/main/src/pages/experience.astro): route page · Dedicated route for work history and experience content. · `src/pages/experience.astro`
- [Works](https://github.com/decimozs/portfolio/blob/main/src/pages/works.astro): route page · Dedicated route for featured projects or works. · `src/pages/works.astro`
- [Notebooks](https://github.com/decimozs/portfolio/blob/main/src/pages/notebooks.astro): route page · Dedicated route for notes, writing, or notebook content. · `src/pages/notebooks.astro`
- [Layout](https://github.com/decimozs/portfolio/blob/main/src/layouts/Layout.astro): shell · Shared page wrapper for site-wide structure and metadata. · `src/layouts/Layout.astro`
- [Main Layout](https://github.com/decimozs/portfolio/blob/main/src/components/main-layout.astro): page chrome · Higher-level shared layout composition for pages. · `src/components/main-layout.astro`
- [Header](https://github.com/decimozs/portfolio/blob/main/src/components/header.astro): navigation chrome · Top-level site header and brand area. · `src/components/header.astro`
- [Nav](https://github.com/decimozs/portfolio/blob/main/src/components/nav.astro): navigation · Primary site navigation links and menu structure. · `src/components/nav.astro`
- [Hamburger](https://github.com/decimozs/portfolio/blob/main/src/components/hamburger.tsx): react toggle · Client-side mobile menu toggle interaction. · `src/components/hamburger.tsx`
- [Smooth Scroll](https://github.com/decimozs/portfolio/blob/main/src/components/smooth-scroll.tsx): client enhancement · Client-side scrolling behavior enhancement. · `src/components/smooth-scroll.tsx`
- [SEO](https://github.com/decimozs/portfolio/blob/main/src/components/SEO.astro): meta component · Metadata and head-tag composition component. · `src/components/SEO.astro`
- [PostHog](https://github.com/decimozs/portfolio/blob/main/src/components/posthog.astro): analytics · Analytics instrumentation component attached at the layout level. · `src/components/posthog.astro`
- [Content Config](https://github.com/decimozs/portfolio/blob/main/src/content.config.ts): content schema · Defines how Astro treats the content layer. · `src/content.config.ts`
- [Experience Data](https://github.com/decimozs/portfolio/blob/main/src/content/experience.json): json content · Primary data source for experience sections. · `src/content/experience.json`
- [Works Data](https://github.com/decimozs/portfolio/blob/main/src/content/works.json): json content · Primary data source for works sections. · `src/content/works.json`
- [Notebook Data](https://github.com/decimozs/portfolio/blob/main/src/content/notebooks.json): json content · Primary data source for notebooks sections. · `src/content/notebooks.json`
- [Constants](https://github.com/decimozs/portfolio/blob/main/src/lib/constant.ts): shared config · Application constants used across pages and components. · `src/lib/constant.ts`
- [Utils](https://github.com/decimozs/portfolio/blob/main/src/lib/utils.ts): helpers · Reusable utility functions for site logic. · `src/lib/utils.ts`
- [SEO Lib](https://github.com/decimozs/portfolio/blob/main/src/lib/seo.ts): meta helper · Shared SEO helpers for metadata generation. · `src/lib/seo.ts`
- [Globals](https://github.com/decimozs/portfolio/blob/main/src/styles/globals.css): global styles · Site-wide stylesheet and design baseline. · `src/styles/globals.css`

### Static Assets

Files served directly from the public directory.

- [Resume PDF](https://github.com/decimozs/portfolio/blob/main/public/resume.pdf): asset · Downloadable resume asset. · `public/resume.pdf`
- [Fonts](https://github.com/decimozs/portfolio/tree/main/public/font): asset pack · Static font files served directly. · `public/font`
- [Robots](https://github.com/decimozs/portfolio/blob/main/public/robots.txt): seo asset · Crawler directives served from the public root. · `public/robots.txt`
- [Manifest](https://github.com/decimozs/portfolio/blob/main/public/site.webmanifest): web app manifest · Site manifest for installed app metadata. · `public/site.webmanifest`

### Tooling

Build, lint, hook, and deployment configuration.

- [Astro Config](https://github.com/decimozs/portfolio/blob/main/astro.config.mjs): framework config · Astro framework and build configuration. · `astro.config.mjs`
- [Package](https://github.com/decimozs/portfolio/blob/main/package.json): project manifest · Scripts and dependency definitions. · `package.json`
- [TypeScript](https://github.com/decimozs/portfolio/blob/main/tsconfig.json): compiler config · TypeScript compiler and path configuration. · `tsconfig.json`
- [Biome](https://github.com/decimozs/portfolio/blob/main/biome.json): lint config · Formatting and linting configuration. · `biome.json`
- [Lefthook](https://github.com/decimozs/portfolio/blob/main/lefthook.yml): git hooks · Pre-commit or local hook automation. · `lefthook.yml`

### CI / Deploy

Automated validation and Cloudflare deployment plumbing.

- [Wrangler](https://github.com/decimozs/portfolio/blob/main/wrangler.jsonc): deploy config · Cloudflare deployment/runtime configuration. · `wrangler.jsonc`
- [CI Workflow](https://github.com/decimozs/portfolio/blob/main/.github/workflows/ci.yml): automation · GitHub Actions validation workflow. · `.github/workflows/ci.yml`

## Connections

- Home → Layout: uses · Home page is wrapped by the shared layout.
- Experience → Layout: uses · Experience page is wrapped by the shared layout.
- Works → Layout: uses · Works page is wrapped by the shared layout.
- Notebooks → Layout: uses · Notebooks page is wrapped by the shared layout.
- Layout → Main Layout: composes · Core layout delegates page chrome to the main layout component.
- Main Layout → Header: includes · Shared page shell includes the header.
- Main Layout → Nav: includes · Shared page shell includes primary navigation.
- Nav → Hamburger: enhanced by · Navigation uses a client-side hamburger toggle for mobile interaction.
- Main Layout → SEO: includes · Shared page shell attaches SEO metadata composition.
- Main Layout → PostHog: includes · Shared page shell attaches analytics instrumentation.
- Main Layout → Smooth Scroll: enhanced by · Shared page shell enables smooth scrolling behavior.
- SEO → SEO Lib: uses · SEO component relies on shared metadata helpers.
- Experience → Experience Data: reads · Experience route renders from experience JSON content.
- Works → Works Data: reads · Works route renders from works JSON content.
- Notebooks → Notebook Data: reads · Notebooks route renders from notebooks JSON content.
- Content Config → Experience Data: defines · Content layer configuration covers experience entries.
- Content Config → Works Data: defines · Content layer configuration covers works entries.
- Content Config → Notebook Data: defines · Content layer configuration covers notebook entries.
- Home → Constants: uses · Home page shares site constants and configuration.
- Home → Utils: uses · Home page uses shared helpers for page logic.
- Main Layout → Globals: loads · Global stylesheet is applied through the shared layout.
- Main Layout → Fonts: serves · Layout depends on static font assets for presentation.
- Home → Resume PDF: links · Home page exposes the downloadable resume asset.
- Astro Config → Content Config: registers · Astro config wires in the content layer.
- Package → Astro Config: scripts · Project scripts build and run the Astro app.
- Package → Biome: uses · Package scripts likely invoke Biome checks.
- Package → Lefthook: uses · Package tooling is connected to git hooks.
- Wrangler → Astro Config: deploys · Wrangler targets the built Astro output for Cloudflare.
- CI Workflow → Package: runs · CI workflow validates the repository via project scripts.
- CI Workflow → Wrangler: checks · CI workflow aligns with Cloudflare deployment config.
- Home → Manifest: uses · Site shell exposes web app manifest metadata.
- Home → Robots: uses · Site output is paired with crawler directives.
