Project Structure
Relevant source files
The following files were used as context for generating this wiki page:This project is a modern web application built with React 19 and Vite, architected using the Feature-Sliced Design (FSD) methodology. The primary goal of this structure is to create a scalable, maintainable, and resilient system by decoupling business logic from the UI and enforcing a unidirectional data flow. This approach organizes the codebase into distinct layers, each with a specific responsibility, preventing "spaghetti dependencies" and promoting modularity.
The architecture is designed to be bleeding-edge, leveraging modern tools to ensure high performance. The FSD structure is key to managing complexity as the application grows, making it easier for developers to navigate, understand, and contribute to the codebase.
Sources: README.md:1-25
Feature-Sliced Design (FSD) Overview
The project's directory structure is organized into layers as defined by Feature-Sliced Design. This architectural pattern enforces strict rules on how layers can interact, ensuring a clear and predictable data flow. The dependencies are unidirectional, with higher layers being able to import from lower layers, but not the other way around.
Sources: README.md:28-29
FSD Layers and Dependency Flow
The diagram below illustrates the hierarchical relationship between the FSD layers used in this project.
This diagram shows the unidirectional dependency rule: a layer can only depend on layers below it.
Layer Responsibilities
| Layer | Responsibility | Examples |
|---|---|---|
| app | Initializes the app, sets up routing, global styles, and providers. | App.tsx, index.css, ThemeProvider |
| pages | Composes widgets and features into complete application pages. | Home.tsx, Projects.tsx |
| widgets | Complex, standalone UI blocks composed of features and entities. | Navbar, Hero, Footer |
| features | User interaction logic and slices of business functionality. | ThemeToggle |
| entities | Core business entities, their data models, and UI representations. | ProjectCard, projectsData |
| shared | Reusable, application-agnostic code, UI kits, and configuration. | Button, config/content.ts, lib/utils |
Sources: README.md:28-29, src/app, src/pages, src/widgets, src/features, src/entities, src/shared
Core Application Setup (app layer)
The app layer is the entry point of the application. It is responsible for assembling the entire application, including routing, global state providers, and base styling.
Sources: src/app/App.tsx, src/app/index.css
Application Component (App.tsx)
App.tsx is the root React component. Its primary responsibilities are:
- Routing: It uses
react-router-domto define all application routes. - Lazy Loading: Pages are lazy-loaded using
React.lazyandReact.Suspenseto improve initial load performance. APageContentSkeletonis shown as a fallback during loading. - Layout Composition: It renders the main layout structure, including the persistent
NavbarandFooterwidgets around the routed page content. - Providers: It wraps the application in a
ThemeProviderto manage the light/dark mode.
The following diagram shows the component composition within App.tsx.
Global Styling and Theming
Global styles and the theming system are defined in src/app/index.css. The application supports both light and dark themes.
- CSS Variables: Semantic CSS variables are defined for both
html[data-theme="light"]andhtml[data-theme="dark"]. These variables control colors for backgrounds, text, borders, and primary actions. - Tailwind CSS: The project uses Tailwind CSS, which is configured to use these CSS variables, making components theme-aware by default.
- Fonts: The application uses "Poppins" and "Roboto Flex" from Google Fonts, which are linked in
index.html.
Sources: src/app/index.css:4-80, index.html:7-13
Page Composition (pages layer)
Pages are responsible for composing widgets and other components to create a view that corresponds to a specific URL.
Sources: src/pages/Home.tsx, src/pages/Projects.tsx
Home Page (Home.tsx)
The home page serves as the main landing page and is composed of several distinct sections, each represented by a widget.
This structure demonstrates how a page acts as an aggregator for larger, independent widget components.
Sources: src/pages/Home.tsx:1-29
Projects Page (Projects.tsx)
The Projects.tsx page demonstrates how a page can directly consume data from the entities layer. It imports projectsData and maps over it to render a list of project details. Each project is displayed in a card format with its image, description, tech stack, and links to the live demo or source code.
Sources: src/pages/Projects.tsx:1-113
Data and Content Management
Project Data (entities layer)
All project-related data is centralized in src/entities/project/model/data.ts. This file exports an array of ProjectCardData objects, providing a single source of truth for all projects showcased in the portfolio.
The structure of a ProjectCardData object is as follows:
| Field | Type | Description |
|---|---|---|
title | string | The title of the project. |
category | string | The category the project belongs to (e.g., "System Architecture"). |
year | number | The year the project was completed. |
src | string | The path to the project's preview image. |
githubLink | string | The URL to the GitHub repository. |
liveLink | string | The URL to the live deployment. |
content | object | An object containing detailed content. |
content.description | string | A detailed description of the project. |
content.tech | string[] | An array of technologies used in the project. |
Sources: src/entities/project/model/data.ts:1-177
Static Content (shared layer)
To facilitate easy updates and maintain consistency, all static UI text (like headlines, button labels, and descriptions) is stored in a single configuration file: src/shared/config/content.ts. Components import text from this file instead of hardcoding it. This centralizes content management and simplifies tasks like localization or global text changes.
For example, the Hero widget imports its headline and subtext directly from this configuration object.
Sources: src/shared/config/content.ts:1-120, src/widgets/Hero/Hero.tsx:7
Build Process and Tooling
The project utilizes a modern frontend toolchain managed via package.json.
Key Dependencies & Scripts
| Tool | Purpose |
|---|---|
vite | A next-generation frontend build tool for development and production builds. |
react | The core UI library (version 19). |
typescript | For static typing. |
tailwindcss | A utility-first CSS framework for styling. |
framer-motion, gsap | Libraries for animations and motion effects. |
sharp | A Node.js library used for high-performance image processing in a build script. |
The scripts section in package.json defines commands for common development tasks:
| Script | Description |
|---|---|
dev | Starts the Vite development server. |
build | Creates a production-ready build of the application in the dist directory. |
lint | Runs ESLint to check for code quality and style issues. |
optimize-images | Executes a custom Node.js script to convert and compress images to WebP format. |
Sources: package.json:1-60, scripts/optimize-images.js
Deployment
The project is configured for deployment on Netlify. The netlify.toml file specifies the build command (npm run build) and the publish directory (dist). It also includes a redirect rule to handle client-side routing and sets security headers like X-Frame-Options and Content-Security-Policy.
Sources: netlify.toml:1-18
Summary
The project's structure, based on Feature-Sliced Design, provides a robust foundation for building a scalable and maintainable web application. By separating concerns into distinct layers (app, pages, widgets, features, entities, shared), the architecture promotes code reuse, simplifies dependency management, and creates a clear mental model for developers. This disciplined approach, combined with a modern toolchain like Vite and React 19, allows for efficient development and a high-performance end product.
Sources: README.md