# calscoo/portfolio architecture

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

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

## Overview

1. This repo has two main concerns: the **portfolio site content/application** built with **Hugo**, and the **infrastructure/deployment stack** built with **Terraform + GitHub Actions**. The site is not hand-served; it is deployed to **AWS Amplify**.

2. The **Hugo application** lives under `hugo/`. It contains the site configuration (`config.toml`), content pages (`content/`), a custom resume page (`content/resume.md`), and at least one custom template override (`layouts/resume/single.html`) for specialized rendering.

3. The visual system is mostly provided by the bundled **Nightfall Hugo theme** in `hugo/themes/nightfall/`. That theme owns the base layout structure, partials, Sass styles, fonts, and page templates that define how the portfolio looks and how common site regions like header/footer/social links are rendered.

4. The repo also includes a small **resume PDF generation script** at `hugo/scripts/generate_resume_pdf.py`. This is a supporting content pipeline step, separate from the web deploy path, suggesting the resume page may be rendered both for the website and as a downloadable PDF artifact.

5. The site build output is generated by Hugo and then consumed by deployment tooling. The generated asset cache under `hugo/resources/_gen/` indicates Hugo’s asset pipeline is used for Sass compilation and related static asset generation.

6. The **infrastructure layer** is in `terraform/`. `main.tf` and `backend.tf` define the AWS resources and state handling needed to create and manage the deployment target. From the README, this stack provisions an **AWS Amplify app**, its **main branch**, a **webhook**, and a **domain association** for custom-domain access.

7. The deployment model is **GitHub → AWS Amplify → hosted portfolio site**. Commits pushed to the connected **main branch** trigger Amplify builds and deployments automatically, so the repository’s source of truth is the GitHub repo and Amplify acts as the delivery platform.

8. **GitHub Actions** is the control plane for infrastructure changes, not for serving the site itself. The workflow in `.github/workflows/deploy.yml` is described as manually triggered to **apply** or **destroy** the Terraform-managed AWS stack, which means GHA is used to stand up or tear down the Amplify-based environment.

9. The key architectural boundary is between **content/build time** and **runtime hosting**: Hugo and its theme generate a static site, while AWS Amplify hosts that static output and handles continuous deployment from GitHub. Terraform sits above both as the provisioning layer.

10. External dependencies that materially affect the architecture are **AWS Amplify** for hosting/builds, **Route53/domain DNS** if a custom domain is used, and **GitHub Actions** plus **GitHub secrets** for AWS credentials during infrastructure operations. This makes the system a fully managed static-site deployment pipeline rather than a custom application server.

11. In diagram terms, the repo decomposes into:
   - **Content & presentation**: Hugo pages, theme, templates, assets
   - **Build artifacts**: generated static site and asset pipeline
   - **Infrastructure as code**: Terraform state and AWS resource definitions
   - **Delivery automation**: GitHub Actions for provisioning, Amplify for continuous deploys

12. The main data flow is: **author content in Hugo → Terraform provisions Amplify → GitHub branch changes trigger Amplify build/deploy → DNS/custom domain points users to the Amplify-hosted site**. The resume PDF script is adjacent to this path, supporting a secondary document-generation use case.

Main entry points: [`terraform/main.tf`](https://github.com/calscoo/portfolio/blob/main/terraform/main.tf) (Terraform stack), [`hugo/content/resume.md`](https://github.com/calscoo/portfolio/blob/main/hugo/content/resume.md) (Resume page), [`hugo/themes/nightfall/layouts`](https://github.com/calscoo/portfolio/tree/main/hugo/themes/nightfall/layouts) (Theme layouts), [`hugo/config.toml`](https://github.com/calscoo/portfolio/blob/main/hugo/config.toml) (Site config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Content & Presentation"]
  node_hugo_config["Site config<br/>Hugo config<br/>[config.toml]"]
  node_site_content["Site content<br/>Hugo content"]
  node_resume_page["Resume page<br/>Hugo page<br/>[resume.md]"]
  node_resume_template["Resume layout<br/>Hugo template<br/>[single.html]"]
  node_nightfall_base["Theme layouts"]
  node_nightfall_assets["Theme styles<br/>Sass and assets"]
end

subgraph group_build["Build Artifacts"]
  node_gen_assets["Generated assets<br/>Hugo resource cache"]
  node_resume_pdf["PDF script<br/>Python utility"]
end

subgraph group_infra["Infrastructure & Delivery"]
  node_tf_main["Terraform stack<br/>Terraform IaC<br/>[main.tf]"]
  node_tf_backend["State backend<br/>Terraform backend<br/>[backend.tf]"]
  node_gha_deploy["Deploy workflow<br/>GitHub Actions<br/>[deploy.yml]"]
  node_amplify_app["Amplify app<br/>AWS hosting"]
  node_amplify_branch["Main branch<br/>Amplify branch"]
  node_amplify_webhook["Webhook"]
  node_domain_assoc["Domain mapping<br/>AWS Route53/Amplify"]
  node_hosted_site(("Portfolio site<br/>Static site"))
end

node_hugo_config -->|"configures"| node_site_content
node_hugo_config -->|"uses theme"| node_nightfall_base
node_site_content -->|"includes"| node_resume_page
node_resume_page -->|"renders with"| node_resume_template
node_resume_template -->|"extends"| node_nightfall_base
node_nightfall_base -->|"styles via"| node_nightfall_assets
node_nightfall_assets -->|"compiles to"| node_gen_assets
node_resume_page -.->|"supports"| node_resume_pdf
node_tf_backend -->|"backs"| node_tf_main
node_gha_deploy -->|"applies"| node_tf_main
node_gha_deploy -->|"stores state"| node_tf_backend
node_tf_main -->|"creates"| node_amplify_app
node_tf_main -->|"creates"| node_amplify_branch
node_tf_main -->|"creates"| node_amplify_webhook
node_tf_main -->|"creates"| node_domain_assoc
node_amplify_branch -->|"deploys to"| node_amplify_app
node_amplify_webhook -->|"triggers"| node_amplify_app
node_amplify_app -->|"serves"| node_hosted_site
node_domain_assoc -->|"points to"| node_hosted_site
node_gen_assets -->|"bundled into"| node_hosted_site

click node_hugo_config "https://github.com/calscoo/portfolio/blob/main/hugo/config.toml"
click node_site_content "https://github.com/calscoo/portfolio/tree/main/hugo/content"
click node_resume_page "https://github.com/calscoo/portfolio/blob/main/hugo/content/resume.md"
click node_resume_template "https://github.com/calscoo/portfolio/blob/main/hugo/layouts/resume/single.html"
click node_nightfall_base "https://github.com/calscoo/portfolio/tree/main/hugo/themes/nightfall/layouts"
click node_nightfall_assets "https://github.com/calscoo/portfolio/tree/main/hugo/themes/nightfall/assets"
click node_gen_assets "https://github.com/calscoo/portfolio/tree/main/hugo/resources/_gen"
click node_resume_pdf "https://github.com/calscoo/portfolio/blob/main/hugo/scripts/generate_resume_pdf.py"
click node_tf_main "https://github.com/calscoo/portfolio/blob/main/terraform/main.tf"
click node_tf_backend "https://github.com/calscoo/portfolio/blob/main/terraform/backend.tf"
click node_gha_deploy "https://github.com/calscoo/portfolio/blob/main/.github/workflows/deploy.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_hugo_config,node_site_content,node_resume_page,node_resume_template,node_nightfall_base,node_nightfall_assets toneBlue
class node_gen_assets,node_resume_pdf toneAmber
class node_tf_main,node_tf_backend,node_gha_deploy,node_amplify_app,node_amplify_branch,node_amplify_webhook,node_domain_assoc,node_hosted_site toneMint
```

## Components

### Content & Presentation

Hugo site structure, theme, and page rendering

- [Site config](https://github.com/calscoo/portfolio/blob/main/hugo/config.toml): Hugo config · Top-level Hugo site settings and theme wiring · `hugo/config.toml`
- [Site content](https://github.com/calscoo/portfolio/tree/main/hugo/content): Hugo content · Portfolio pages and section content · `hugo/content`
- [Resume page](https://github.com/calscoo/portfolio/blob/main/hugo/content/resume.md): Hugo page · Special resume content rendered by Hugo · `hugo/content/resume.md`
- [Resume layout](https://github.com/calscoo/portfolio/blob/main/hugo/layouts/resume/single.html): Hugo template · Custom single-page override for the resume · `hugo/layouts/resume/single.html`
- [Theme layouts](https://github.com/calscoo/portfolio/tree/main/hugo/themes/nightfall/layouts): Hugo theme layouts · Base templates, page shells, and shared partials · `hugo/themes/nightfall/layouts`
- [Theme styles](https://github.com/calscoo/portfolio/tree/main/hugo/themes/nightfall/assets): Sass and assets · Theme styling, fonts, and static presentation assets · `hugo/themes/nightfall/assets`

### Build Artifacts

Generated assets and supporting document pipeline

- [Generated assets](https://github.com/calscoo/portfolio/tree/main/hugo/resources/_gen): Hugo resource cache · Hugo's compiled Sass and asset pipeline output · `hugo/resources/_gen`
- [PDF script](https://github.com/calscoo/portfolio/blob/main/hugo/scripts/generate_resume_pdf.py): Python utility · Support script for generating a resume PDF artifact · `hugo/scripts/generate_resume_pdf.py`

### Infrastructure & Delivery

Terraform provisioning and GitHub Actions automation

- [Terraform stack](https://github.com/calscoo/portfolio/blob/main/terraform/main.tf): Terraform IaC · AWS Amplify deployment resources and environment definition · `terraform/main.tf`
- [State backend](https://github.com/calscoo/portfolio/blob/main/terraform/backend.tf): Terraform backend · Remote state and Terraform backend configuration · `terraform/backend.tf`
- [Deploy workflow](https://github.com/calscoo/portfolio/blob/main/.github/workflows/deploy.yml): GitHub Actions · Manual workflow to apply or destroy the Terraform stack · `.github/workflows/deploy.yml`
- **Amplify app**: AWS hosting · Managed build-and-host platform for the portfolio site
- **Main branch**: Amplify branch · Connected branch that triggers continuous deployment
- **Webhook**: Amplify webhook · Trigger path used for deployment automation
- **Domain mapping**: AWS Route53/Amplify · Custom-domain association for hosted access
- **Portfolio site**: Static site · Public site served from AWS Amplify

## Connections

- Site config → Site content: configures · Site settings define how content is built
- Site config → Theme layouts: uses theme · Configuration points the site at the bundled theme
- Site content → Resume page: includes · Resume is a specialized content page
- Resume page → Resume layout: renders with · Custom layout overrides default rendering
- Resume layout → Theme layouts: extends · Custom page rendering sits on top of theme layouts
- Theme layouts → Theme styles: styles via · Theme layouts are paired with theme Sass and static assets
- Theme styles → Generated assets: compiles to · Hugo asset pipeline produces generated CSS and related outputs
- Resume page → PDF script: supports · Script provides an alternate PDF output path for the resume
- State backend → Terraform stack: backs · Terraform state backend supports the deployment stack
- Deploy workflow → Terraform stack: applies · Workflow provisions or tears down AWS resources
- Deploy workflow → State backend: stores state · Workflow depends on Terraform backend configuration
- Terraform stack → Amplify app: creates · Terraform provisions the Amplify hosting app
- Terraform stack → Main branch: creates · Terraform configures the connected main branch
- Terraform stack → Webhook: creates · Terraform provisions deployment trigger integration
- Terraform stack → Domain mapping: creates · Terraform binds the app to a custom domain
- Main branch → Amplify app: deploys to · Branch changes trigger Amplify builds and deploys
- Webhook → Amplify app: triggers · Webhook can initiate Amplify deployment actions
- Amplify app → Portfolio site: serves · Amplify hosts the public portfolio site
- Domain mapping → Portfolio site: points to · Custom domain resolves users to the hosted site
- Generated assets → Portfolio site: bundled into · Generated CSS/assets become part of the deployed static site
