# ramxcodes/sleek-portfolio architecture

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

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

## Overview

1. This is a Next.js 15 App Router portfolio site, so the main architectural boundary is route-based rendering under `src/app`. Each major page is a separate route: home, blog, projects, journey, work experience, resume, setup, gears, and contact.

2. The site is content-driven rather than CMS-driven. Blog posts, project writeups, and journey content live as MDX files in `src/data/*`, and route pages under `src/app/blog/[slug]` and `src/app/projects/[slug]` read that content through helpers in `src/lib/blog.ts` and `src/lib/project.ts`.

3. The UI is organized by feature area in `src/components/*`. There are reusable “common” primitives for layout and navigation, domain-specific components for blog/projects/experience/contact, and landing-page sections that compose the home page from smaller blocks like Hero, About, Projects, Journey, Blog, Experience, Setup, and CTA.

4. A large portion of the repo is a design-system layer built on shadcn/ui primitives in `src/components/ui`. These components provide the interactive building blocks used throughout the app: dialogs, forms, tabs, sheets, menus, tooltips, sliders, and similar controls.

5. Styling and shell behavior are global and centralized. `src/app/layout.tsx` and `src/app/globals.css` define the application frame, while theme-related providers and switches live in `src/components/common/ThemeProviders.tsx` and `ThemeSwitch.tsx`. Tailwind CSS is the styling system, with shadcn patterns layered on top.

6. Content and presentation are separated by a config layer in `src/config`. These files hold the editable text, links, metadata, and section settings for areas like Hero, Navbar, Projects, Experience, Resume, Footer, Contact, Gears, and SEO metadata, so most site customization happens without touching route code.

7. The contact and chat features are the main server-side/API boundary. `src/app/api/contact/route.ts` handles the contact form submission flow and is tied to Telegram integration, while `src/app/api/chat/route.ts` provides a chat endpoint, likely backed by the configured Gemini API key. The repo also includes `src/validate/testTelegram.ts` to verify Telegram wiring.

8. External integrations are intentionally lightweight and user-facing. Telegram is used as the message delivery backend for the contact form, Gemini is used for chat, and Umami is used for privacy-focused analytics through `src/components/analytics/UmamiAnalytics.tsx` and `src/hooks/use-umami.ts`.

9. Static assets are fully local and served from `public`. That includes blog/project images, fonts, setup files, the animated cat script, and other media referenced by the pages and content components. This makes the portfolio self-contained aside from the external APIs and analytics script.

10. There is a clear split between server-rendered content pages and small client-side enhancements. Hooks like `use-mobile`, `use-haptic-feedback`, `use-umami`, and the Lenis integration add interactivity, while components such as `BackToTop`, `FontSizeControls`, `ChatBubble`, and `OnekoCat` enhance the UX without changing the content model.

11. The repo is optimized for static content workflows and easy expansion. New blog posts and projects are added by creating MDX files plus matching assets, while new visual technologies/icons are added as isolated SVG/icon components under `src/components/technologies` or `src/components/svgs`.

12. Operationally, the project is designed for Bun/Node development and Vercel deployment. Environment variables wire in Telegram, Gemini, the site URL, and Umami, and the presence of `next.config.ts`, GitHub workflow linting, and Husky pre-commit hooks shows a strong focus on build-time correctness rather than runtime infrastructure.

Main entry points: [`public`](https://github.com/ramxcodes/sleek-portfolio/tree/main/public) (Public assets), [`src/components/common`](https://github.com/ramxcodes/sleek-portfolio/tree/main/src/components/common) (Common UI), [`src/components`](https://github.com/ramxcodes/sleek-portfolio/tree/main/src/components) (Domain UI), [`src/components/analytics`](https://github.com/ramxcodes/sleek-portfolio/tree/main/src/components/analytics) (Integrations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routes["App routes"]
  node_app_layout["Root layout<br/>next layout<br/>[layout.tsx]"]
  node_app_home["Home<br/>page route<br/>[page.tsx]"]
  node_app_blog["Blog routes<br/>page route<br/>[page.tsx]"]
  node_app_blog_post["Blog post<br/>dynamic route<br/>[page.tsx]"]
  node_app_projects["Projects routes<br/>page route<br/>[page.tsx]"]
  node_app_project["Project page<br/>dynamic route<br/>[page.tsx]"]
  node_app_contact_api["Contact API<br/>route handler<br/>[route.ts]"]
  node_app_chat_api["Chat API<br/>route handler<br/>[route.ts]"]
end

subgraph group_content["Content layer"]
  node_content_blog["Blog MDX<br/>content source"]
  node_content_projects["Project MDX<br/>content source"]
  node_content_journey["Journey MDX<br/>content source<br/>[journey.mdx]"]
  node_lib_blog["Blog loader<br/>content helper<br/>[blog.ts]"]
  node_lib_project["Project loader<br/>content helper<br/>[project.ts]"]
  node_config_site["Site config<br/>content config"]
end

subgraph group_ui["UI system"]
  node_landing_sections["Landing sections<br/>section components"]
  node_common_ui["Common UI<br/>shared components"]
  node_content_ui["Domain UI<br/>domain components"]
  node_shadcn_ui["UI primitives<br/>design system"]
end

subgraph group_infra["Infrastructure"]
  node_hooks["Client hooks"]
  node_integrations["Integrations<br/>external services"]
  node_assets[("Public assets<br/>static assets")]
end

node_app_layout -->|"wraps"| node_common_ui
node_app_layout -.->|"uses"| node_shadcn_ui
node_app_home -->|"composes"| node_landing_sections
node_app_home -.->|"reads"| node_config_site
node_app_blog -->|"loads"| node_lib_blog
node_app_blog_post -->|"loads"| node_lib_blog
node_app_blog_post -.->|"reads"| node_content_blog
node_app_projects -->|"loads"| node_lib_project
node_app_project -->|"loads"| node_lib_project
node_app_project -.->|"reads"| node_content_projects
node_app_contact_api -->|"sends"| node_integrations
node_app_chat_api -->|"calls"| node_integrations
node_app_blog -->|"renders"| node_content_ui
node_app_project -->|"renders"| node_content_ui
node_landing_sections -->|"uses"| node_content_ui
node_content_ui -->|"built on"| node_shadcn_ui
node_common_ui -.->|"enhanced by"| node_hooks
node_common_ui -.->|"tracks"| node_integrations
node_config_site -.->|"references"| node_assets
node_content_blog -.->|"references"| node_assets
node_content_projects -.->|"references"| node_assets
node_assets -.->|"served by"| node_app_home
node_assets -.->|"illustrates"| node_landing_sections
node_hooks -.->|"supports"| node_common_ui
node_integrations -.->|"mounted in"| node_app_layout

click node_app_layout "https://github.com/ramxcodes/sleek-portfolio/blob/main/src/app/layout.tsx"
click node_app_home "https://github.com/ramxcodes/sleek-portfolio/blob/main/src/app/page.tsx"
click node_app_blog "https://github.com/ramxcodes/sleek-portfolio/blob/main/src/app/blog/page.tsx"
click node_app_blog_post "https://github.com/ramxcodes/sleek-portfolio/blob/main/src/app/blog/[slug]/page.tsx"
click node_app_projects "https://github.com/ramxcodes/sleek-portfolio/blob/main/src/app/projects/page.tsx"
click node_app_project "https://github.com/ramxcodes/sleek-portfolio/blob/main/src/app/projects/[slug]/page.tsx"
click node_app_contact_api "https://github.com/ramxcodes/sleek-portfolio/blob/main/src/app/api/contact/route.ts"
click node_app_chat_api "https://github.com/ramxcodes/sleek-portfolio/blob/main/src/app/api/chat/route.ts"
click node_content_blog "https://github.com/ramxcodes/sleek-portfolio/tree/main/src/data/blog"
click node_content_projects "https://github.com/ramxcodes/sleek-portfolio/tree/main/src/data/projects"
click node_content_journey "https://github.com/ramxcodes/sleek-portfolio/blob/main/src/data/journey/journey.mdx"
click node_lib_blog "https://github.com/ramxcodes/sleek-portfolio/blob/main/src/lib/blog.ts"
click node_lib_project "https://github.com/ramxcodes/sleek-portfolio/blob/main/src/lib/project.ts"
click node_config_site "https://github.com/ramxcodes/sleek-portfolio/tree/main/src/config"
click node_landing_sections "https://github.com/ramxcodes/sleek-portfolio/tree/main/src/components/landing"
click node_common_ui "https://github.com/ramxcodes/sleek-portfolio/tree/main/src/components/common"
click node_content_ui "https://github.com/ramxcodes/sleek-portfolio/tree/main/src/components"
click node_shadcn_ui "https://github.com/ramxcodes/sleek-portfolio/tree/main/src/components/ui"
click node_hooks "https://github.com/ramxcodes/sleek-portfolio/tree/main/src/hooks"
click node_integrations "https://github.com/ramxcodes/sleek-portfolio/tree/main/src/components/analytics"
click node_assets "https://github.com/ramxcodes/sleek-portfolio/tree/main/public"

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_app_layout,node_app_home,node_app_blog,node_app_blog_post,node_app_projects,node_app_project,node_app_contact_api,node_app_chat_api toneBlue
class node_content_blog,node_content_projects,node_content_journey,node_lib_blog,node_lib_project,node_config_site toneAmber
class node_landing_sections,node_common_ui,node_content_ui,node_shadcn_ui toneMint
class node_hooks,node_integrations,node_assets toneRose
```

## Components

### App routes

Next.js App Router pages and API endpoints.

- [Root layout](https://github.com/ramxcodes/sleek-portfolio/blob/main/src/app/layout.tsx): next layout · Global shell, providers, and shared frame. · `src/app/layout.tsx`
- [Home](https://github.com/ramxcodes/sleek-portfolio/blob/main/src/app/page.tsx): page route · Landing page assembled from section components. · `src/app/page.tsx`
- [Blog routes](https://github.com/ramxcodes/sleek-portfolio/blob/main/src/app/blog/page.tsx): page route · Blog listing and slug pages. · `src/app/blog/page.tsx`
- [Blog post](https://github.com/ramxcodes/sleek-portfolio/blob/main/src/app/blog/[slug]/page.tsx): dynamic route · Individual blog post rendering from MDX. · `src/app/blog/[slug]/page.tsx`
- [Projects routes](https://github.com/ramxcodes/sleek-portfolio/blob/main/src/app/projects/page.tsx): page route · Project listing and slug pages. · `src/app/projects/page.tsx`
- [Project page](https://github.com/ramxcodes/sleek-portfolio/blob/main/src/app/projects/[slug]/page.tsx): dynamic route · Individual project rendering from MDX. · `src/app/projects/[slug]/page.tsx`
- [Contact API](https://github.com/ramxcodes/sleek-portfolio/blob/main/src/app/api/contact/route.ts): route handler · Server-side contact submission endpoint. · `src/app/api/contact/route.ts`
- [Chat API](https://github.com/ramxcodes/sleek-portfolio/blob/main/src/app/api/chat/route.ts): route handler · Server-side chat endpoint. · `src/app/api/chat/route.ts`

### Content layer

MDX content, typed models, and loaders.

- [Blog MDX](https://github.com/ramxcodes/sleek-portfolio/tree/main/src/data/blog): content source · Blog post content files. · `src/data/blog`
- [Project MDX](https://github.com/ramxcodes/sleek-portfolio/tree/main/src/data/projects): content source · Project writeups and case studies. · `src/data/projects`
- [Journey MDX](https://github.com/ramxcodes/sleek-portfolio/blob/main/src/data/journey/journey.mdx): content source · Journey content source. · `src/data/journey/journey.mdx`
- [Blog loader](https://github.com/ramxcodes/sleek-portfolio/blob/main/src/lib/blog.ts): content helper · Loads and shapes blog content. · `src/lib/blog.ts`
- [Project loader](https://github.com/ramxcodes/sleek-portfolio/blob/main/src/lib/project.ts): content helper · Loads and shapes project content. · `src/lib/project.ts`
- [Site config](https://github.com/ramxcodes/sleek-portfolio/tree/main/src/config): content config · Editable text, metadata, and section settings. · `src/config`

### UI system

Reusable components, design-system primitives, and page sections.

- [Landing sections](https://github.com/ramxcodes/sleek-portfolio/tree/main/src/components/landing): section components · Hero, About, Projects, Journey, Blog, Experience, Setup, CTA. · `src/components/landing`
- [Common UI](https://github.com/ramxcodes/sleek-portfolio/tree/main/src/components/common): shared components · Layout, navigation, theme, and utility components. · `src/components/common`
- [Domain UI](https://github.com/ramxcodes/sleek-portfolio/tree/main/src/components): domain components · Blog, project, experience, contact, gears, and certificates UI. · `src/components`
- [UI primitives](https://github.com/ramxcodes/sleek-portfolio/tree/main/src/components/ui): design system · Reusable shadcn/ui interaction primitives. · `src/components/ui`

### Infrastructure

Styling, assets, hooks, and external integrations.

- [Client hooks](https://github.com/ramxcodes/sleek-portfolio/tree/main/src/hooks): hooks · Responsive, haptic, analytics, and scrolling helpers. · `src/hooks`
- [Integrations](https://github.com/ramxcodes/sleek-portfolio/tree/main/src/components/analytics): external services · Telegram, Gemini, and Umami integration surfaces. · `src/components/analytics`
- [Public assets](https://github.com/ramxcodes/sleek-portfolio/tree/main/public): static assets · Local images, fonts, setup files, and oneko script. · `public`

## Connections

- Root layout → Common UI: wraps · Provides shared providers, navigation, footer, and theme shell.
- Root layout → UI primitives: uses · Imports design-system primitives for app shell interactions.
- Home → Landing sections: composes · Builds the landing page from feature sections.
- Home → Site config: reads · Pulls copy, links, and section settings from config.
- Blog routes → Blog loader: loads · Fetches blog index and metadata.
- Blog post → Blog loader: loads · Resolves slugged blog content and rendering data.
- Blog post → Blog MDX: reads · Consumes MDX posts from the content directory.
- Projects routes → Project loader: loads · Fetches project index and metadata.
- Project page → Project loader: loads · Resolves slugged project content and rendering data.
- Project page → Project MDX: reads · Consumes MDX project writeups.
- Contact API → Integrations: sends · Delivers contact messages through Telegram.
- Chat API → Integrations: calls · Uses the configured Gemini-backed chat flow.
- Blog routes → Domain UI: renders · Uses blog list and post presentation components.
- Project page → Domain UI: renders · Uses project detail and navigation components.
- Landing sections → Domain UI: uses · Composes reusable feature-specific UI blocks.
- Domain UI → UI primitives: built on · Leverages dialogs, forms, tabs, menus, and other primitives.
- Common UI → Client hooks: enhanced by · Client-side utilities power mobile, haptic, and scroll behavior.
- Common UI → Integrations: tracks · Analytics and chat affordances connect to external services.
- Site config → Public assets: references · Site settings point to local media and downloadable files.
- Blog MDX → Public assets: references · Blog MDX can embed local images and media.
- Project MDX → Public assets: references · Project MDX can embed local images, screenshots, and media.
- Public assets → Home: served by · Static files support the rendered pages and sections.
- Public assets → Landing sections: illustrates · Provides imagery, fonts, and setup artifacts used in the UI.
- Client hooks → Common UI: supports · Hooks power responsive and interactive common components.
- Integrations → Root layout: mounted in · Analytics and chat integrations are wired through the app shell.
