Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 43 additions & 47 deletions architecture/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,68 +2,64 @@

[Open the interactive system map](https://www.theodoreoy.com/architecture/).

The viewer maps the website's content, build, deployment, and browser interactions.
It supports label search, light and dark themes, relationship
tracing, and image export. A downloaded `index.html` also works offline.
The viewer maps content inputs, static rendering, validation, GitHub Pages delivery,
and browser interactions. It supports label search, light and dark themes,
relationship tracing, and image export.

| File | Responsibility |
| --- | --- |
| `site.json` | Editable Archify definition of the current system |
| `index.html` | Standalone interactive viewer |
| `README.md` | Viewer usage and maintenance |
| `LICENSE` | MIT license for the Archify viewer |
| `LICENSE` | MIT license for the viewer |

The primary navigation contains About and Experience. Twenty-three canonical content
routes cover these pages, three Selected Research manuscripts, and eighteen Experience
detail pages. Eight compatibility pages bring the content export to thirty-one routes.
This viewer at `/architecture/` makes thirty-two exported routes, excluding 404.
`website/app/lib/content/` defines identity, routes, content loaders, and research
Markdown and math rendering. `website/content/` contains approved Experience copy,
structured manuscripts, frozen source evidence, and integrity contracts. GitHub
Actions publishes the assembled `website/out/` export to GitHub Pages on the custom domain.
## System represented

About opens with its interactive Canvas2D name entrance before the profile. The navigation
menu, shared article contents, and legal-note previews run in the browser. The website uses no request-time API, database,
authentication, or analytics. The [maintenance guide](../docs/maintenance.md)
documents content ownership, output contracts, security, and publishing.
`website/app/lib/content/` owns identity, routing, content loading, and research
Markdown/math rendering. Experience presents five categories and eighteen entries;
About includes three Selected Research papers. The AI portfolio's single maintained
source is `website/content/sources/ai-portfolio/ai-research-and-engineering.md`;
its importer generates the AI showcase fields and four article JSON files.
Selected Research uses pinned Markdown/TeX inputs with provenance; legal manuscripts
use structured paragraph runs and footnotes. The [maintenance guide](../docs/maintenance.md)
describes content ownership, import commands, and extension checks.

About presents three Selected Research entries with links to on-site manuscripts
and research summaries. Critical Dependence Stress for Portfolio Diversification
appears first, followed by the Asian-options and Rough Heston papers. Article headers
contain the return link, title, GitHub link, and Full Manuscript link. Reading content
begins at Abstract; pre-abstract front matter stays in the protected source. The
articles include core chapters (dependence stress 1–5; Asian options 1–10; Rough
Heston 1–8) and references; appendices are linked on GitHub. Each source JSON records
its exact upstream commit, blob, and manuscript URL. Frozen manuscript evidence lives
in `website/content/sources/selected-research/`. The `dependence/` subdirectory contains
the dependence-stress paper's frozen TeX files and independent provenance record;
`website/scripts/import-dependence-research.mjs` imports that manuscript deterministically.
Next.js exports HTML, CSS, and JavaScript to `website/out/`. Build assembly includes
this viewer and applies production CSP before GitHub Actions deploys the artifact
to GitHub Pages. There is no request-time API, database, authentication, or analytics.
The main site's browser interactions are the Canvas2D entrance, navigation menu,
article contents, and legal-note previews. Reading and ordinary links remain
available without JavaScript.

The main website takes its grid, warm paper color, and fine rules from Cognition as
a design reference and uses self-hosted Inter. Page titles and section headings use
22px, entry headings use 18px, and body text uses 14px. Experience directory labels
and numbers use 18px; formulas use 1.15em. The architecture viewer has independent
diagram controls and geometry and shares the site's HTML type roles.
## Update the viewer

Update `site.json` from the current source and `.github/workflows/pages.yml`, then
validate and generate it with the installed Archify skill:
Update `site.json` against the current application and `.github/workflows/pages.yml`,
then run these commands from the repository root. `<archify>` is the installed
Archify skill directory.

```sh
node <archify>/bin/archify.mjs validate architecture architecture/site.json --quality showcase --json
node <archify>/bin/archify.mjs deliver architecture architecture/site.json architecture/index.html --quality showcase --json
node website/scripts/integrate-architecture.mjs
npm --prefix website run check
```

Run these commands from the repository root. `<archify>` is the local Archify skill
directory. The integration script applies the website's six HTML type roles,
major-section heading semantics, and normalized control labels while preserving
SVG geometry. The viewer loads
`../assets/fonts/inter.css`, preloads regular Inter, and inherits `--font-text`.
Visual exports embed the local regular and italic Inter files in SVG; PNG and WebM
render from the same prepared fonts. The integration is safe to run repeatedly.
Run `npm --prefix website run check` to verify the complete export, including the
viewer and its production content security policy.
The integration applies shared HTML type roles, responsive reader layout,
major-section heading semantics, control labels, and export-font settings while
preserving SVG geometry. It handles both freshly generated and already integrated
viewers; running it again should leave the current viewer unchanged.

The viewer uses the MIT license. Published pages use the website's self-hosted Inter
fonts under the SIL Open Font License, included with the font assets. A standalone
offline HTML file uses system sans fallbacks when those font assets are unavailable.
The viewer loads `../assets/fonts/inter.css`, preloads regular Inter, and inherits
the site's fixed optical axis of 14 and lining numerals. General page and module
headings use 22px, secondary headings 18px, and body/control text 14px at every
viewport. Diagram labels retain their own SVG coordinate sizes. On the main site,
inline formulas use 1em and displayed formulas 1.15em.

SVG exports embed the local regular and italic Inter files and retain the same
fixed optical settings; PNG and WebM render from those prepared fonts. Check theme
switching, search, tracing, keyboard controls, responsive layout, and export after
regeneration. The complete build also verifies the viewer's production CSP and
local assets.

The standalone HTML works offline with system sans fallbacks when font assets are
unavailable. The viewer uses the MIT license; the self-hosted Inter files use the
SIL Open Font License included beside the font assets.
7 changes: 3 additions & 4 deletions docs/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,7 @@ introductions are omitted. Summaries use upright
black body text at 14px; project and organization titles use the 18px subheading
role. No content is truncated to fit a card.

The black and blue in the approved Word document identify outer and detail content;
blue is not a prose color on the website. All body copy uses the existing ink colors.
All body copy uses the shared ink colors.
Blue remains reserved for navigation, hover, and keyboard focus.

All eighteen entries use real Read More links to dedicated pages. The eight AI and
Expand All @@ -100,8 +99,8 @@ keyboard focus and touch targets. Do not repeat the outer summary in the detail

AI pages include the scope disclosure, Key Contributions with any nested method
lists, Architectural Context, and the numbered manuscript chapters. Thin rules
separate top-level contribution items across all detail pages. The frozen original
manuscript and explicit reviewed corrections retain the content's provenance.
separate top-level contribution items across all detail pages. A single authoritative
AI manuscript supplies the introductory copy, nested lists, and complete mathematical body.
Legal pages place Key Contributions
before the complete Abstract and manuscript. The shared contents rail includes
the contribution block and source chapter links. Return links target the matching
Expand Down
Loading
Loading