How calscoo/portfolio works
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: main.tf Terraform stack · resume.md Resume page · layouts Theme layouts · config.toml Site config
Components 16
Content & Presentation
Hugo site structure, theme, and page rendering
- Site config · Top-level Hugo site settings and theme wiring
hugo/config.toml - Site content · Portfolio pages and section content
hugo/content - Resume page · Special resume content rendered by Hugo
hugo/content/resume.md - Resume layout · Custom single-page override for the resume
hugo/layouts/resume/single.html - Theme layouts · Base templates, page shells, and shared partials
hugo/themes/nightfall/layouts - Theme styles · Theme styling, fonts, and static presentation assets
hugo/themes/nightfall/assets
Build Artifacts
Generated assets and supporting document pipeline
- Generated assets · Hugo's compiled Sass and asset pipeline output
hugo/resources/_gen - PDF script · Support script for generating a resume PDF artifact
hugo/scripts/generate_resume_pdf.py
Infrastructure & Delivery
Terraform provisioning and GitHub Actions automation
- Terraform stack · AWS Amplify deployment resources and environment definition
terraform/main.tf - State backend · Remote state and Terraform backend configuration
terraform/backend.tf - Deploy workflow · Manual workflow to apply or destroy the Terraform stack
.github/workflows/deploy.yml - Amplify app · Managed build-and-host platform for the portfolio site
- Main branch · Connected branch that triggers continuous deployment
- Webhook · Trigger path used for deployment automation
- Domain mapping · Custom-domain association for hosted access
- Portfolio site · Public site served from AWS Amplify
Connections 20
- 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