# seman2-dev/gitfolio-md architecture

> Architecture diagram of the GitHub repository seman2-dev/gitfolio-md, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/seman2-dev/gitfolio-md
- Repository: https://github.com/seman2-dev/gitfolio-md

## Overview

Gitfolio.md is a GitHub profile README builder with hosted SVG and data APIs. Users configure profile details, sections, and themes in the builder; GitHub imports and featured repositories supply data, while preview and Markdown generation produce a README that can be copied, downloaded, or shared. Hosted endpoints render matching SVGs and serve GitHub data, shares, and visitor counts. Edges reflect excerpts, source-index references, or README statements; unsampled routes are represented at their existing directories, and their internal wiring is not asserted.

Main entry points: [`components/BuilderClient.tsx`](https://github.com/seman2-dev/gitfolio-md/blob/main/components/BuilderClient.tsx) (Builder editor), [`app/api`](https://github.com/seman2-dev/gitfolio-md/tree/main/app/api) (Image endpoints), [`components/preview/Preview.tsx`](https://github.com/seman2-dev/gitfolio-md/blob/main/components/preview/Preview.tsx) (Live preview), [`lib/markdown.ts`](https://github.com/seman2-dev/gitfolio-md/blob/main/lib/markdown.ts) (README generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editor["README Builder"]
  node_landing["Landing page<br/>[page.tsx]"]
  node_builder["Builder editor<br/>[BuilderClient.tsx]"]
  node_profilepanel["Profile panel<br/>[ProfilePanel.tsx]"]
  node_sectionspanel["Sections panel<br/>[SectionsPanel.tsx]"]
  node_themepanel["Theme panel<br/>[ThemePanel.tsx]"]
  node_contentpanel["Content panel<br/>[ContentPanel.tsx]"]
  node_preview["Live preview<br/>[Preview.tsx]"]
  node_markdownview["Markdown view<br/>[MarkdownView.tsx]"]
  node_shareui["Share dialog<br/>[ShareDialog.tsx]"]
end

subgraph group_content["Content Generation"]
  node_config["Config defaults &amp; safety<br/>[config.ts]"]
  node_defaults["Section defaults<br/>[defaults.ts]"]
  node_themes["Theme resolution<br/>[themes.ts]"]
  node_markdown["README generator<br/>[markdown.ts]"]
  node_skills["Skills &amp; badges<br/>[skills.ts]"]
  node_socials["Social links<br/>[socials.ts]"]
  node_svg["SVG renderer<br/>[svg.ts]"]
  node_svgmodern["Modern SVG designs<br/>[svg-modern.ts]"]
  node_svgvariants["SVG design variants<br/>[svg-variants.ts]"]
end

subgraph group_services["Backend Services"]
  node_api_client["Browser API client<br/>[api.ts]"]
  node_imageapi["Image endpoints"]
  node_githubapi["GitHub data endpoints"]
  node_shareapi["Share endpoints"]
  node_githubsvc["GitHub data service<br/>[github.ts]"]
  node_http["HTTP response handling<br/>[http.ts]"]
end

subgraph group_state["Persistence &amp; Controls"]
  node_validation["Request validation<br/>[validate.ts]"]
  node_store[("Persistent store<br/>[store.ts]")]
  node_ratelimit["Rate limiting<br/>[ratelimit.ts]"]
end

node_visitor(("README author"))
node_github["GitHub API"]

node_visitor -->|"opens"| node_landing
node_visitor -->|"configures"| node_builder
node_builder -->|"renders"| node_profilepanel
node_builder -->|"renders"| node_sectionspanel
node_builder -->|"renders"| node_themepanel
node_builder -->|"renders"| node_contentpanel
node_builder -->|"previews"| node_preview
node_builder -->|"shows"| node_markdownview
node_builder -->|"opens"| node_shareui
node_builder -->|"fetches data"| node_api_client
node_builder -->|"generates"| node_markdown
node_builder -->|"loads config"| node_config
node_builder -->|"initializes"| node_defaults
node_shareui -->|"saves or loads"| node_api_client
node_preview -->|"renders SVG"| node_svg
node_preview -->|"uses helpers"| node_markdown
node_preview -->|"formats badges"| node_skills
node_preview -->|"resolves theme"| node_themes
node_markdown -->|"uses presets"| node_themes
node_markdown -->|"uses badges"| node_skills
node_markdown -->|"formats links"| node_socials
node_svg -->|"dispatches designs"| node_svgmodern
node_svg -->|"dispatches designs"| node_svgvariants
node_svg -->|"resolves colors"| node_themes
node_imageapi -->|"renders images"| node_svg
node_imageapi -->|"wraps responses"| node_http
node_imageapi -->|"parses queries"| node_validation
node_imageapi -->|"loads profile data"| node_githubsvc
node_imageapi -->|"updates counters"| node_store
node_imageapi -->|"checks client IP"| node_ratelimit
node_githubapi -->|"serves GitHub data"| node_githubsvc
node_githubsvc -->|"requests data"| node_github
node_http -->|"checks limits"| node_ratelimit
node_shareapi -->|"saves or loads"| node_store
node_shareapi -->|"sanitizes designs"| node_config
node_shareapi -->|"returns responses"| node_http
node_validation -->|"parses theme"| node_themes
node_validation -->|"uses errors"| node_githubsvc
node_store -->|"retains counts"| node_visitor

click node_landing "https://github.com/seman2-dev/gitfolio-md/blob/main/app/page.tsx"
click node_builder "https://github.com/seman2-dev/gitfolio-md/blob/main/components/BuilderClient.tsx"
click node_profilepanel "https://github.com/seman2-dev/gitfolio-md/blob/main/components/panels/ProfilePanel.tsx"
click node_sectionspanel "https://github.com/seman2-dev/gitfolio-md/blob/main/components/panels/SectionsPanel.tsx"
click node_themepanel "https://github.com/seman2-dev/gitfolio-md/blob/main/components/panels/ThemePanel.tsx"
click node_contentpanel "https://github.com/seman2-dev/gitfolio-md/blob/main/components/panels/ContentPanel.tsx"
click node_preview "https://github.com/seman2-dev/gitfolio-md/blob/main/components/preview/Preview.tsx"
click node_markdownview "https://github.com/seman2-dev/gitfolio-md/blob/main/components/preview/MarkdownView.tsx"
click node_shareui "https://github.com/seman2-dev/gitfolio-md/blob/main/components/ShareDialog.tsx"
click node_api_client "https://github.com/seman2-dev/gitfolio-md/blob/main/lib/api.ts"
click node_config "https://github.com/seman2-dev/gitfolio-md/blob/main/lib/config.ts"
click node_defaults "https://github.com/seman2-dev/gitfolio-md/blob/main/lib/defaults.ts"
click node_themes "https://github.com/seman2-dev/gitfolio-md/blob/main/lib/themes.ts"
click node_markdown "https://github.com/seman2-dev/gitfolio-md/blob/main/lib/markdown.ts"
click node_skills "https://github.com/seman2-dev/gitfolio-md/blob/main/lib/skills.ts"
click node_socials "https://github.com/seman2-dev/gitfolio-md/blob/main/lib/socials.ts"
click node_svg "https://github.com/seman2-dev/gitfolio-md/blob/main/lib/svg.ts"
click node_svgmodern "https://github.com/seman2-dev/gitfolio-md/blob/main/lib/svg-modern.ts"
click node_svgvariants "https://github.com/seman2-dev/gitfolio-md/blob/main/lib/svg-variants.ts"
click node_imageapi "https://github.com/seman2-dev/gitfolio-md/tree/main/app/api"
click node_githubapi "https://github.com/seman2-dev/gitfolio-md/tree/main/app/api/github"
click node_shareapi "https://github.com/seman2-dev/gitfolio-md/tree/main/app/api/share"
click node_githubsvc "https://github.com/seman2-dev/gitfolio-md/blob/main/lib/server/github.ts"
click node_http "https://github.com/seman2-dev/gitfolio-md/blob/main/lib/server/http.ts"
click node_validation "https://github.com/seman2-dev/gitfolio-md/blob/main/lib/server/validate.ts"
click node_store "https://github.com/seman2-dev/gitfolio-md/blob/main/lib/server/store.ts"
click node_ratelimit "https://github.com/seman2-dev/gitfolio-md/blob/main/lib/server/ratelimit.ts"

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_landing,node_builder,node_profilepanel,node_sectionspanel,node_themepanel,node_contentpanel,node_preview,node_markdownview,node_shareui toneBlue
class node_config,node_defaults,node_themes,node_markdown,node_skills,node_socials,node_svg,node_svgmodern,node_svgvariants toneAmber
class node_api_client,node_imageapi,node_githubapi,node_shareapi,node_githubsvc,node_http,node_github toneMint
class node_validation,node_store,node_ratelimit toneRose
class node_visitor toneIndigo
```

## Components

### README Builder

- [Landing page](https://github.com/seman2-dev/gitfolio-md/blob/main/app/page.tsx): `app/page.tsx`
- [Builder editor](https://github.com/seman2-dev/gitfolio-md/blob/main/components/BuilderClient.tsx): `components/BuilderClient.tsx`
- [Profile panel](https://github.com/seman2-dev/gitfolio-md/blob/main/components/panels/ProfilePanel.tsx): `components/panels/ProfilePanel.tsx`
- [Sections panel](https://github.com/seman2-dev/gitfolio-md/blob/main/components/panels/SectionsPanel.tsx): `components/panels/SectionsPanel.tsx`
- [Theme panel](https://github.com/seman2-dev/gitfolio-md/blob/main/components/panels/ThemePanel.tsx): `components/panels/ThemePanel.tsx`
- [Content panel](https://github.com/seman2-dev/gitfolio-md/blob/main/components/panels/ContentPanel.tsx): `components/panels/ContentPanel.tsx`
- [Live preview](https://github.com/seman2-dev/gitfolio-md/blob/main/components/preview/Preview.tsx): `components/preview/Preview.tsx`
- [Markdown view](https://github.com/seman2-dev/gitfolio-md/blob/main/components/preview/MarkdownView.tsx): `components/preview/MarkdownView.tsx`
- [Share dialog](https://github.com/seman2-dev/gitfolio-md/blob/main/components/ShareDialog.tsx): `components/ShareDialog.tsx`

### Content Generation

- [Config defaults & safety](https://github.com/seman2-dev/gitfolio-md/blob/main/lib/config.ts): `lib/config.ts`
- [Section defaults](https://github.com/seman2-dev/gitfolio-md/blob/main/lib/defaults.ts): `lib/defaults.ts`
- [Theme resolution](https://github.com/seman2-dev/gitfolio-md/blob/main/lib/themes.ts): `lib/themes.ts`
- [README generator](https://github.com/seman2-dev/gitfolio-md/blob/main/lib/markdown.ts): `lib/markdown.ts`
- [Skills & badges](https://github.com/seman2-dev/gitfolio-md/blob/main/lib/skills.ts): `lib/skills.ts`
- [Social links](https://github.com/seman2-dev/gitfolio-md/blob/main/lib/socials.ts): `lib/socials.ts`
- [SVG renderer](https://github.com/seman2-dev/gitfolio-md/blob/main/lib/svg.ts): `lib/svg.ts`
- [Modern SVG designs](https://github.com/seman2-dev/gitfolio-md/blob/main/lib/svg-modern.ts): `lib/svg-modern.ts`
- [SVG design variants](https://github.com/seman2-dev/gitfolio-md/blob/main/lib/svg-variants.ts): `lib/svg-variants.ts`

### Backend Services

- [Browser API client](https://github.com/seman2-dev/gitfolio-md/blob/main/lib/api.ts): `lib/api.ts`
- [Image endpoints](https://github.com/seman2-dev/gitfolio-md/tree/main/app/api): `app/api`
- [GitHub data endpoints](https://github.com/seman2-dev/gitfolio-md/tree/main/app/api/github): `app/api/github`
- [Share endpoints](https://github.com/seman2-dev/gitfolio-md/tree/main/app/api/share): `app/api/share`
- [GitHub data service](https://github.com/seman2-dev/gitfolio-md/blob/main/lib/server/github.ts): `lib/server/github.ts`
- [HTTP response handling](https://github.com/seman2-dev/gitfolio-md/blob/main/lib/server/http.ts): `lib/server/http.ts`

### Persistence & Controls

- [Request validation](https://github.com/seman2-dev/gitfolio-md/blob/main/lib/server/validate.ts): `lib/server/validate.ts`
- [Persistent store](https://github.com/seman2-dev/gitfolio-md/blob/main/lib/server/store.ts): `lib/server/store.ts`
- [Rate limiting](https://github.com/seman2-dev/gitfolio-md/blob/main/lib/server/ratelimit.ts): `lib/server/ratelimit.ts`

### Other components

- **README author**
- **GitHub API**

## Connections

- README author → Landing page: opens (evidence: `README.md`)
- README author → Builder editor: configures (evidence: `README.md`)
- Builder editor → Profile panel: renders (evidence: `components/BuilderClient.tsx`)
- Builder editor → Sections panel: renders (evidence: `components/BuilderClient.tsx`)
- Builder editor → Theme panel: renders (evidence: `components/BuilderClient.tsx`)
- Builder editor → Content panel: renders (evidence: `components/BuilderClient.tsx`)
- Builder editor → Live preview: previews (evidence: `components/BuilderClient.tsx`)
- Builder editor → Markdown view: shows (evidence: `components/BuilderClient.tsx`)
- Builder editor → Share dialog: opens (evidence: `components/BuilderClient.tsx`)
- Builder editor → Browser API client: fetches data (evidence: `components/BuilderClient.tsx`)
- Builder editor → README generator: generates (evidence: `components/BuilderClient.tsx`)
- Builder editor → Config defaults & safety: loads config (evidence: `components/BuilderClient.tsx`)
- Builder editor → Section defaults: initializes (evidence: `components/BuilderClient.tsx`)
- Share dialog → Browser API client: saves or loads (evidence: `components/ShareDialog.tsx`)
- Live preview → SVG renderer: renders SVG (evidence: `components/preview/Preview.tsx`)
- Live preview → README generator: uses helpers (evidence: `components/preview/Preview.tsx`)
- Live preview → Skills & badges: formats badges (evidence: `components/preview/Preview.tsx`)
- Live preview → Theme resolution: resolves theme (evidence: `components/preview/Preview.tsx`)
- README generator → Theme resolution: uses presets (evidence: `lib/markdown.ts`)
- README generator → Skills & badges: uses badges (evidence: `lib/markdown.ts`)
- README generator → Social links: formats links (evidence: `lib/markdown.ts`)
- SVG renderer → Modern SVG designs: dispatches designs (evidence: `lib/svg.ts`)
- SVG renderer → SVG design variants: dispatches designs (evidence: `lib/svg.ts`)
- SVG renderer → Theme resolution: resolves colors (evidence: `lib/svg.ts`)
- Image endpoints → SVG renderer: renders images (evidence: `app/api/activity/route.ts`)
- Image endpoints → HTTP response handling: wraps responses (evidence: `app/api/activity/route.ts`)
- Image endpoints → Request validation: parses queries (evidence: `app/api/activity/route.ts`)
- Image endpoints → GitHub data service: loads profile data (evidence: `app/api/activity/route.ts`)
- Image endpoints → Persistent store: updates counters (evidence: `app/api/visitors/route.ts`)
- Image endpoints → Rate limiting: checks client IP (evidence: `app/api/visitors/route.ts`)
- GitHub data endpoints → GitHub data service: serves GitHub data (evidence: `README.md`)
- GitHub data service → GitHub API: requests data (evidence: `lib/server/github.ts`)
- HTTP response handling → Rate limiting: checks limits (evidence: `lib/server/http.ts`)
- Share endpoints → Persistent store: saves or loads (evidence: `app/api/share/route.ts`)
- Share endpoints → Config defaults & safety: sanitizes designs (evidence: `app/api/share/route.ts`)
- Share endpoints → HTTP response handling: returns responses (evidence: `app/api/share/route.ts`)
- Request validation → Theme resolution: parses theme (evidence: `lib/server/validate.ts`)
- Request validation → GitHub data service: uses errors (evidence: `lib/server/validate.ts`)
- Persistent store → README author: retains counts (evidence: `README.md`)
