Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Portfolio OS is a web-based interactive portfolio designed to mimic a macOS-style desktop environment. It is built using Next.js 15, React 19, and Tailwind CSS, utilizing a component-based architecture to manage a multi-window interface, internationalization, and responsive design patterns for both desktop and mobile users.
The core of the application revolves around a centralized window management system that handles the lifecycle of various "apps" (About, Projects, Contact) within a virtual desktop environment.
Sources: app/layout.tsx, package.json, README.md
Core Framework and Configuration
The project is built on the Next.js App Router architecture. It utilizes next-intl for internationalization, supporting English (LTR) and Persian (RTL) locales. The styling is driven by Tailwind CSS 4, utilizing a custom "Liquid Glass" design system defined in the global CSS to achieve macOS-like translucency and vibrancy.
Tech Stack Summary
| Category | Technology |
|---|---|
| Framework | Next.js 16.2.9 (App Router) |
| UI Library | React 19.2.4 |
| Styling | Tailwind CSS 4, shadcn/ui |
| Icons | Lucide React |
| Testing | Vitest |
| Linting/Formatting | Biome |
Sources: package.json:17-38, app/layout.tsx:12-35, app/globals.css:126-160
Window Management System
The application employs a centralized state management pattern for handling windows using a React Context and a reducer-based workflow.
Window State Logic
The windowReducer handles all state transitions for the desktop environment. It ensures single-instance application logic, meaning re-opening an app focuses and restores the existing window rather than creating a duplicate.
The state tracks windows (an array of active app instances) and focusedId (the ID of the window currently at the top of the stack).
Sources: workflows/windowManager.test.ts:18-87, context/WindowManagerContext.tsx:21-46
Data Structures
Key interfaces define the geometry and identification of windows within the system.
| Interface | Properties | Description |
|---|---|---|
AppId | "about" | "projects" | "contact" | Unique identifier for registered applications. |
Geometry | x, y, width, height | Spatial coordinates and dimensions of a window. |
WindowState | id, appId, zIndex, isMinimized, ... | The complete state of an active window instance. |
Sources: types/index.ts:1-8, context/WindowManagerContext.tsx:8-19
Desktop UI Components
The desktop environment consists of three primary visual layers: the Menu Bar, the Desktop (containing widgets and wallpaper), and the Dock.
Menu Bar
The MenuBar acts as the global navigation and status indicator. It dynamically updates the active application title based on the focusedId from the WindowManagerContext. If no window is focused, it defaults to "Finder".
Sources: features/desktop/components/MenuBar.tsx:24-32
Desktop Environment
- Wallpaper: A layered SVG component generating a Tahoe-style scenic background without external assets.
- Widgets: Locale-aware components including a Calendar (calculating dates relative to a reference Monday) and a Weather widget.
- Mobile Experience: The
MobileHomecomponent replaces the windowed desktop on smaller screens, using a full-screen grid of app tiles and a simplified navigation stack.
Content and Feature Modules
The portfolio's content is decoupled from the UI logic, stored in a central library (lib/content.ts). Feature-specific logic is encapsulated in dedicated directories.
- About: Displays role, bio, and skills defined in
lib/content.ts. - Projects: Renders a grid of projects with tags and external links.
- Contact: A simulated form using a custom
useContactFormhook.
Sources: lib/content.ts:1-44, features/about/components/AboutApp.tsx:6-30, features/projects/components/ProjectsApp.tsx:7-40
Conclusion
The architecture of Portfolio OS leverages Modern React patterns to create a complex, stateful UI that remains responsive across devices. By separating window management logic from feature components and centralizing content, the project maintains a clear distinction between the "OS" framework and the portfolio data it displays.