# midudev/minimalist-portfolio-json architecture

> Architecture diagram of the GitHub repository midudev/minimalist-portfolio-json, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/midudev/minimalist-portfolio-json
- Repository: https://github.com/midudev/minimalist-portfolio-json

## Overview

##### Project Type and Purpose
- This is a **static, component-based portfolio/CV website** built with Astro and TypeScript.
- Its source of truth is a JSON resume (`cv.json`) following the JSON Resume schema.
- It compiles to plain HTML/CSS/JS (static site) with a small client-side keyboard-shortcut component (Ninja Keys).

##### File Structure Analysis
- **Top level**
- astro.config.mjs, tsconfig.json – Astro + TypeScript configs
- package.json / pnpm-lock.yaml – dependencies & scripts (dev, build, preview)
- public/ – static assets served as-is
- **src/pages/** – the single entry point `index.astro`
- **src/layouts/Layout.astro** – global wrapper
- **src/components/** – generic UI pieces plus sections under `components/sections/*` (Hero, About, Experience, etc.)
- **src/cv.d.ts**, cv.json – typed JSON content that drives rendering

##### Key README Insights
- Uses **Astro** as a static-site framework.
- **TypeScript** for typing across components & JSON schema.
- **Ninja Keys** for a client-side keyboard menu.
- Build/Dev commands: `pnpm dev`, `pnpm build`, `pnpm preview`.

##### Main Architecture Components
a. **Developer Machine** (pnpm, Corepack)
b. **Astro Build System**
- Reads `astro.config.mjs` + TypeScript config
- Loads `src/pages/index.astro` + Layout + Components
- Parses `cv.json` via typed declarations (cv.d.ts)
- Applies templating to output static HTML/CSS/JS in `dist/`
c. **Public Assets** (`public/`)
- favicon, images (logo.png, portada.png), any other static files
d. **Client-Side JavaScript**
- Bundle with Ninja Keys (keyboard shortcuts)
- Minimal interactivity injected into the static page
e. **Hosting / CDN**
- Serves the contents of `dist/` to end users; no dynamic server logic

##### Relationships & Data Flow
(1) Developer runs `pnpm dev` or `pnpm build`
→ (2) Astro reads config + TypeScript schemas
→ (3) Astro pulls in `cv.json` data → passes data into each Section component
→ (4) Components render HTML fragments
→ (5) Layout wraps them into a full page
→ (6) Static HTML/CSS/JS emitted to `dist/`
→ (7) In browser, Ninja Keys JS activates keyboard menu
→ (8) Browser displays final page

##### Architectural Patterns & Principles
- **Static Site Generation (SSG):** All HTML rendered at build time.
- **Component Composition:** Atomic & section-level Astro components for reusability.
- **Strong Typing:** JSON data typed with `.d.ts` files ensures data correctness.
- **Separation of Concerns:**
- Data (cv.json) vs. Presentation (Astro components)
- Static assets (`public/`) vs. source code (`src/`)

##### Technologies & Frameworks
- **Astro** – SSG framework
- **TypeScript** – static typing
- **Ninja Keys** – client-side keyboard menu
- **pnpm/Corepack** – package management
- **JSON Resume schema** – data structure for CV

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    Dev["Developer\n(pnpm/Corepack)"]:::external
    click Dev "https://github.com/midudev/minimalist-portfolio-json/blob/main/package.json"

    %% Build Pipeline
    subgraph "Build Pipeline"
        AstroConfig["astro.config.mjs"]:::build
        TSConfig["tsconfig.json"]:::build
        PackageMgmt["package.json / pnpm-lock.yaml"]:::build
        BuildProcess["Astro Build System"]:::build
    end
    click AstroConfig "https://github.com/midudev/minimalist-portfolio-json/blob/main/astro.config.mjs"
    click TSConfig "https://github.com/midudev/minimalist-portfolio-json/blob/main/tsconfig.json"
    click PackageMgmt "https://github.com/midudev/minimalist-portfolio-json/blob/main/package.json"
    click PackageMgmt "https://github.com/midudev/minimalist-portfolio-json/blob/main/pnpm-lock.yaml"

    %% Source Code
    subgraph "Source Code"
        CvJson["cv.json / cv_english.json"]:::source
        CvDts["src/cv.d.ts"]:::source
        TypesDts["src/types.d.ts"]:::source
        EnvDts["src/env.d.ts"]:::source
        Pages["src/pages/index.astro"]:::source
        Layout["src/layouts/Layout.astro"]:::source
        Public["public/"]:::source
        KeyboardManager["src/components/KeyboardManager.astro"]:::source
        SectionWrapper["src/components/Section.astro"]:::source
        subgraph "Section Components"
            Hero["Hero.astro"]:::source
            About["About.astro"]:::source
            Experience["Experience.astro"]:::source
            Education["Education.astro"]:::source
            Projects["Projects.astro"]:::source
            Skills["Skills.astro"]:::source
        end
        Icons["src/icons/"]:::source
    end
    click CvJson "https://github.com/midudev/minimalist-portfolio-json/blob/main/cv.json"
    click CvDts "https://github.com/midudev/minimalist-portfolio-json/blob/main/src/cv.d.ts"
    click TypesDts "https://github.com/midudev/minimalist-portfolio-json/blob/main/src/types.d.ts"
    click EnvDts "https://github.com/midudev/minimalist-portfolio-json/blob/main/src/env.d.ts"
    click Pages "https://github.com/midudev/minimalist-portfolio-json/blob/main/src/pages/index.astro"
    click Layout "https://github.com/midudev/minimalist-portfolio-json/blob/main/src/layouts/Layout.astro"
    click Public "https://github.com/midudev/minimalist-portfolio-json/tree/main/public/"
    click KeyboardManager "https://github.com/midudev/minimalist-portfolio-json/blob/main/src/components/KeyboardManager.astro"
    click SectionWrapper "https://github.com/midudev/minimalist-portfolio-json/blob/main/src/components/Section.astro"
    click Hero "https://github.com/midudev/minimalist-portfolio-json/blob/main/src/components/sections/Hero.astro"
    click About "https://github.com/midudev/minimalist-portfolio-json/blob/main/src/components/sections/About.astro"
    click Experience "https://github.com/midudev/minimalist-portfolio-json/blob/main/src/components/sections/Experience.astro"
    click Education "https://github.com/midudev/minimalist-portfolio-json/blob/main/src/components/sections/Education.astro"
    click Projects "https://github.com/midudev/minimalist-portfolio-json/blob/main/src/components/sections/Projects.astro"
    click Skills "https://github.com/midudev/minimalist-portfolio-json/blob/main/src/components/sections/Skills.astro"
    click Icons "https://github.com/midudev/minimalist-portfolio-json/tree/main/src/icons/"

    %% Output
    subgraph "Output (dist/)"
        Dist["Static HTML/CSS/JS"]:::output
    end

    %% Hosting/CDN
    subgraph "Hosting/CDN"
        CDN["Hosting/CDN"]:::external
    end

    %% Client Browser
    subgraph "Client Browser"
        Browser["Browser"]:::runtime
        NinjaKeys["Ninja Keys (JS)"]:::runtime
    end

    %% Connections
    Dev -->|"runs dev/build"| BuildProcess
    BuildProcess --> AstroConfig
    BuildProcess --> TSConfig
    BuildProcess --> PackageMgmt
    BuildProcess --> CvJson
    BuildProcess --> Pages
    BuildProcess --> Public
    Pages --> Layout
    Layout --> SectionWrapper
    CvJson --> Hero
    CvJson --> About
    CvJson --> Experience
    CvJson --> Education
    CvJson --> Projects
    CvJson --> Skills
    Hero --> Pages
    About --> Pages
    Experience --> Pages
    Education --> Pages
    Projects --> Pages
    Skills --> Pages
    Icons --> SectionWrapper
    BuildProcess --> Dist
    Public --> Dist
    Dist --> CDN
    CDN --> Browser
    Browser --> NinjaKeys

    %% Styles
    classDef build fill:#cce5ff,stroke:#004085,color:#004085;
    classDef source fill:#e2e3e5,stroke:#6c757d,color:#383d41;
    classDef output fill:#d4edda,stroke:#155724,color:#155724;
    classDef runtime fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
```
