feat: add initial README.md with project overview, structure, and usage instructions

README.md

@@ -0,0 +1,160 @@
+# Frontend Monorepo Template
+
+![Turborepo](https://img.shields.io/badge/Turborepo-2.7.2-red?style=flat\&logo=turborepo)
+![pnpm](https://img.shields.io/badge/pnpm-8.15.6-orange?style=flat\&logo=pnpm)
+![Node.js](https://img.shields.io/badge/Node.js-v24.11.1-green?style=flat\&logo=nodedotjs)
+![Vite](https://img.shields.io/badge/Vite-Bundler-blue?style=flat\&logo=vite)
+![React](https://img.shields.io/badge/React-Framework-cyan?style=flat\&logo=react)
+![TypeScript](https://img.shields.io/badge/TypeScript-Language-blue?style=flat\&logo=typescript)
+![Vitest](https://img.shields.io/badge/Vitest-Testing-green?style=flat\&logo=vitest)
+
+A **scalable, enterprise-ready frontend monorepo template** built with **Turborepo**, **pnpm**, and **Vite**.
+This repository is designed for long-term maintainability, featuring:
+
+* Shared logic and UI libraries
+* Centralized tooling configuration
+* Turbo-powered task orchestration and caching
+* Dedicated documentation & component playground using Storybook
+
+---
+
+## 📂 Repository Structure
+
+The monorepo is organized into **Apps** (deployable applications) and **Packages** (shared libraries).
+
+```text
+.
+├── apps/
+│   ├── web/              # Main React Application (Vite + TypeScript)
+│   └── docs-dev/         # Component Documentation & Playground (Storybook)
+│
+├── packages/
+│   ├── ui/               # Shared UI Component Library
+│   ├── utils/            # Shared Utilities (Date, Encryption, Core Logic, etc)
+│   └── configs/          # Shared Tooling Configurations
+│       ├── eslint/       # Shared ESLint rules
+│       └── typescript/   # Shared TypeScript (tsconfig) bases
+│
+├── package.json          # Root scripts and dependencies
+├── pnpm-workspace.yaml   # pnpm workspace definition
+└── turbo.json            # Turborepo pipeline configuration
+```
+
+---
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+Ensure your local environment matches the following versions to avoid compatibility issues:
+
+* **Node.js**: `v24.11.1`
+* **pnpm**: `v8.15.6`
+  (Enforced via the `packageManager` field in `package.json`)
+
+### Installation
+
+Install all dependencies from the **root directory**:
+
+```bash
+pnpm install
+```
+
+---
+
+## 🛠 Usage & Scripts
+
+This repository uses **Turborepo** to orchestrate tasks efficiently. All commands are executed from the root.
+
+### Development
+
+| Command             | Description                                                                 |
+| ------------------- | --------------------------------------------------------------------------- |
+| `pnpm dev`          | Start **all applications** (`web` and `docs-dev`) in parallel               |
+| `pnpm dev:web`      | Start only the **Main Web App** (usually at `http://localhost:5173`)        |
+| `pnpm dev:docs-dev` | Start **Storybook** for UI development (usually at `http://localhost:6006`) |
+
+### Building & Quality
+
+| Command          | Description                                   |
+| --------------------- | --------------------------------------------- |
+| `pnpm build`          | Build all apps and packages using Turbo cache |
+| `pnpm build:web`      | Build only the web application                |
+| `pnpm build:docs-dev` | Build only the docs-dev application                |
+| `pnpm test`           | Run unit tests (Vitest) across all packages   |
+| `pnpm lint`           | Run ESLint across the workspace               |
+| `pnpm format`         | Format code using Prettier                    |
+
+---
+
+## 📦 Packages Overview
+
+### 1. `apps/web`
+
+The main consumer-facing application.
+
+* Imports business logic from `@repo/utils`
+* Uses shared UI components from `@repo/ui`
+
+**Tech Stack**:
+
+* React
+* Vite
+* TypeScript
+* Tailwind CSS
+
+---
+
+### 2. `apps/docs-dev` (Storybook)
+
+An isolated environment for developing and documenting UI components.
+
+* Ensures components in `@repo/ui` are built and tested independently
+* Acts as a living design system and playground
+
+---
+
+### 3. `packages/utils`
+
+Shared business logic and reusable utility modules that can be consumed across multiple applications. Fully tested using Vitest.
+
+This package is intended to hold non-UI, cross-cutting logic such as date/time handling, security helpers, and other common utilities. It is designed to be framework-agnostic, predictable, and easy to extend as the system evolves.
+
+---
+
+### 4. `packages/ui`
+
+Shared UI component library (Buttons, Inputs, Cards, Layouts).
+
+* Ensures consistent design across all applications
+* Designed to be consumed by both web apps and Storybook
+
+---
+
+### 5. `packages/configs`
+
+Single source of truth for tooling configuration.
+
+* **eslint-config**: Shared ESLint rules (React, libraries, Storybook)
+* **typescript-config**: Shared `tsconfig.json` base configurations
+
+---
+
+## ⚙️ Configuration & Environment
+
+
+### Turborepo Caching
+
+This repository uses **Turborepo caching** for builds, tests, and other artifacts.
+
+To fully clean the workspace (dependencies, build outputs, and Turbo cache):
+
+```bash
+rm -rf node_modules **/*/node_modules .turbo **/*/.turbo dist **/*/dist
+```
+
+---
+
+## 📝 License
+
+This project is **private and proprietary**.