PROJECT OVERVIEW:
The application, titled 'Marka Pusula' (Brand Compass), aims to solve the problem of brand name fragmentation and confusion, particularly when a single brand uses the same or similar names across numerous products and features, as exemplified by Microsoft's 'Copilot' naming. The core value proposition is to provide a centralized, visually intuitive platform for businesses to catalog, categorize, visualize, and manage their product naming conventions, thereby enhancing brand clarity and reducing user confusion. It will serve as a single source of truth for a company's product nomenclature.
TECH STACK:
- Frontend Framework: React (using Create React App or Vite for project setup)
- Styling: Tailwind CSS for rapid UI development and consistent design.
- State Management: Zustand or Redux Toolkit for efficient global state management.
- Routing: React Router DOM for client-side navigation.
- Data Visualization: Visx or D3.js for interactive network graph visualization.
- Form Handling: React Hook Form for robust form management.
- Icons: Heroicons or Lucide React for a clean icon set.
- Deployment: Netlify or Vercel for seamless CI/CD and hosting.
CORE FEATURES:
1. **Product Ingestion & Management:**
* **User Flow:** Users can access a dashboard with an 'Add Product' button. Clicking it opens a modal or a dedicated form. Fields include: Product Name (required), Short Description (optional), Category (dropdown/tags, pre-defined or custom), Relationship to Parent Product (optional, dropdown linking to existing products), Notes (textarea). Upon submission, the product is added to the user's catalog.
* **Details:** Input validation for product name uniqueness within the user's account. Categories can be managed (add, edit, delete) from a settings page.
2. **Categorization & Tagging:**
* **User Flow:** During product addition, users select from predefined categories (e.g., 'Software Application', 'Platform Feature', 'Hardware', 'Service', 'AI Model', 'Documentation') or create custom tags. Products can have multiple tags. A dedicated 'Categories/Tags Management' section allows users to view, edit, rename, or delete their custom categories and tags.
* **Details:** Categories provide a primary organizational structure. Tags allow for more granular, cross-categorical grouping (e.g., '#AI', '#Cloud', '#Mobile').
3. **Interactive Visualization:**
* **User Flow:** A dedicated 'Visualization' page displays a network graph. Nodes represent products, and edges represent relationships (e.g., 'is part of', 'is a feature of', 'is built upon'). Users can click on nodes to highlight connections, zoom in/out, and pan. Hovering over a node displays a tooltip with the product name, category, and short description.
* **Details:** The graph should dynamically render based on the added products and their defined relationships. Users can filter the visualization by category or tag.
4. **Search & Filtering:**
* **User Flow:** A persistent search bar is available on the dashboard and visualization pages. Users can type keywords to search product names and descriptions. Filter options (dropdowns/checkboxes) allow filtering by category and tags. Search results update dynamically as the user types or applies filters.
* **Details:** Search should be fast and efficient, leveraging client-side filtering for smaller datasets or potentially integrating with a backend search service for larger accounts.
UI/UX DESIGN:
- **Layout:** Single Page Application (SPA) structure. A clean, minimalist dashboard displaying product lists and summary statistics. A dedicated page for the interactive visualization. A separate settings/management area.
- **Color Palette:** Primary: Deep Blue (#1E3A8A), Secondary: Teal (#14B8A6), Accent: Yellow (#FBBF24), Neutral: Grays (#F3F4F6, #D1D5DB, #4B5563).
- **Typography:** Sans-serif font like Inter or Poppins for readability. Clear hierarchy using font weights and sizes.
- **Responsive Design:** Mobile-first approach. Utilizing Tailwind CSS's responsive modifiers (sm:, md:, lg:, xl:) to ensure usability across all devices. Navigation should adapt to smaller screens (e.g., hamburger menu).
- **Interactivity:** Smooth transitions for modals, filters, and graph interactions. Clear visual feedback on hover states and active elements.
COMPONENT BREAKDOWN:
- `App.jsx`: Main application wrapper, sets up routing.
- `DashboardPage.jsx`: Displays product summary, recent additions, and a link to visualization. Includes `ProductList.jsx` and `AddProductButton.jsx`.
- `ProductList.jsx`: Renders a list or table of products. Accepts `products` array as prop. Includes `ProductListItem.jsx`.
- `ProductListItem.jsx`: Displays a single product's summary information. Accepts `product` object as prop.
- `AddProductModal.jsx`: Modal component for adding/editing products. Contains `ProductForm.jsx`.
- `ProductForm.jsx`: Form elements for product details. Accepts `initialData`, `onSubmit`, `onCancel` props.
- `VisualizationPage.jsx`: Main visualization component. Fetches product data and renders the `NetworkGraph.jsx`.
- `NetworkGraph.jsx`: Uses Visx/D3 to render the interactive graph. Accepts `nodes` and `links` data, `onNodeClick` callback.
- `SearchBar.jsx`: Input component for global search. Accepts `onSearch` callback.
- `FilterPanel.jsx`: Component for category/tag filtering. Accepts `categories`, `tags`, `onFilterChange` callback.
- `CategoryManager.jsx`: Page/component for managing categories and tags.
- `Header.jsx`: Top navigation bar.
- `Footer.jsx`.
DATA MODEL:
- **State Structure (Zustand/Redux):**
```javascript
{
products: Product[];
categories: Category[];
tags: Tag[];
filters: { categories: string[]; tags: string[]; searchTerm: string };
visualizationSettings: { layout: string; linkType: string };
isLoading: boolean;
error: string | null;
}
```
- **Product Interface:**
```typescript
interface Product {
id: string;
name: string;
description: string;
category: string;
tags: string[];
parentId: string | null; // For relationships
createdAt: string;
updatedAt: string;
}
```
- **Category Interface:**
```typescript
interface Category {
id: string;
name: string;
}
```
- **Tag Interface:**
```typescript
interface Tag {
id: string;
name: string;
}
```
- **Mock Data Format:** All data will be stored in local state initially. For persistence, Local Storage API can be used for MVP, or a backend API (e.g., Firebase, Supabase) for scalability.
ANIMATIONS & INTERACTIONS:
- **Modals:** Fade-in/slide-up effect for `AddProductModal`.
- **Transitions:** Smooth transitions between pages using React Router transitions (e.g., `Framer Motion`).
- **Graph Interactions:** Smooth zooming and panning in `NetworkGraph.jsx`. Subtle scaling or glow effect on node hover. Animated transitions when adding/removing nodes or links.
- **Loading States:** Skeleton loaders or spinners (`react-spinners`) for data fetching or filtering operations. Button disable states with loading indicators.
- **Micro-interactions:** Subtle hover effects on buttons and list items. Feedback on form submission (e.g., success/error messages).
EDGE CASES:
- **Empty State:** Display user-friendly messages and clear calls-to-action on the dashboard and visualization pages when no products have been added yet (e.g., "You haven't added any products yet. Click 'Add Product' to get started!").
- **Error Handling:** Graceful error handling for API calls (if applicable) or local storage operations. Display informative error messages to the user.
- **Validation:** Client-side and potentially server-side validation for product names (uniqueness, required field), categories, and relationships. Clear inline error messages.
- **Accessibility (a11y):** Use semantic HTML elements. Ensure keyboard navigability for all interactive components. Provide ARIA attributes where necessary. Sufficient color contrast.
- **Data Integrity:** Prevent orphan relationships (e.g., linking to a non-existent `parentId`). Handle deletion of categories/tags that are in use.
SAMPLE DATA:
1. **Products:**
```json
[
{ "id": "prod_001", "name": "Microsoft Copilot", "description": "AI companion for productivity", "category": "Software Application", "tags": ["AI", "Productivity", "SaaS"], "parentId": null, "createdAt": "2023-01-15T10:00:00Z", "updatedAt": "2023-10-26T12:30:00Z" },
{ "id": "prod_002", "name": "Copilot for Microsoft 365", "description": "AI features integrated into Office apps", "category": "Platform Feature", "tags": ["AI", "Office", "Enterprise"], "parentId": "prod_001", "createdAt": "2023-03-20T11:00:00Z", "updatedAt": "2023-10-26T12:35:00Z" },
{ "id": "prod_003", "name": "Windows Copilot", "description": "AI assistant in Windows 11", "category": "Software Application", "tags": ["AI", "Windows", "OS"], "parentId": "prod_001", "createdAt": "2023-05-10T09:30:00Z", "updatedAt": "2023-10-26T12:40:00Z" },
{ "id": "prod_004", "name": "GitHub Copilot", "description": "AI pair programmer", "category": "Developer Tool", "tags": ["AI", "Coding", "Developer"], "parentId": null, "createdAt": "2021-06-30T14:00:00Z", "updatedAt": "2023-10-26T12:45:00Z" },
{ "id": "prod_005", "name": "Copilot (Surface Laptop)", "description": "Laptops featuring AI capabilities", "category": "Hardware", "tags": ["AI", "Laptop", "Surface"], "parentId": null, "createdAt": "2023-09-21T16:00:00Z", "updatedAt": "2023-10-26T12:50:00Z" },
{ "id": "prod_006", "name": "Copilot Studio", "description": "Tool for building custom Copilots", "category": "Developer Tool", "tags": ["AI", "Low-Code", "Automation"], "parentId": "prod_001", "createdAt": "2023-11-01T10:00:00Z", "updatedAt": "2023-11-01T10:00:00Z" }
]
```
2. **Categories:**
```json
[
{ "id": "cat_001", "name": "Software Application" },
{ "id": "cat_002", "name": "Platform Feature" },
{ "id": "cat_003", "name": "Hardware" },
{ "id": "cat_004", "name": "Developer Tool" },
{ "id": "cat_005", "name": "Service" },
{ "id": "cat_006", "name": "Documentation" }
]
```
3. **Tags:**
```json
[
{ "id": "tag_001", "name": "AI" },
{ "id": "tag_002", "name": "Productivity" },
{ "id": "tag_003", "name": "SaaS" },
{ "id": "tag_004", "name": "Office" },
{ "id": "tag_005", "name": "Enterprise" },
{ "id": "tag_006", "name": "Windows" },
{ "id": "tag_007", "name": "OS" },
{ "id": "tag_008", "name": "Coding" },
{ "id": "tag_009", "name": "Developer" },
{ "id": "tag_010", "name": "Laptop" },
{ "id": "tag_011", "name": "Surface" },
{ "id": "tag_012", "name": "Low-Code" },
{ "id": "tag_013", "name": "Automation" },
{ "id": "tag_014", "name": "Cloud" },
{ "id": "tag_015", "name": "Mobile" }
]
```
DEPLOYMENT NOTES:
- Ensure environment variables (e.g., API keys if backend is used) are configured correctly in the deployment platform (Netlify/Vercel).
- Build command: Typically `npm run build` or `yarn build`.
- Output directory: `dist` or `build`.
- For optimal performance, code splitting should be handled by the build tool (Vite/CRA). Analyze bundle sizes and optimize imports.
- Consider implementing basic caching strategies for frequently accessed data if using local storage to improve load times.
- Set up CI/CD pipelines for automatic deployments on code pushes to the main branch.