{"id":27064800,"url":"https://github.com/beastmp/biz-tracker-web","last_synced_at":"2026-05-11T07:12:26.406Z","repository":{"id":283937846,"uuid":"953282648","full_name":"beastmp/biz-tracker-web","owner":"beastmp","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-30T22:27:52.000Z","size":785,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-31T09:16:04.519Z","etag":null,"topics":["project-biz-tracker","react","web"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beastmp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-23T01:35:27.000Z","updated_at":"2025-05-16T21:11:16.000Z","dependencies_parsed_at":"2025-03-23T07:20:42.898Z","dependency_job_id":"ae0f20eb-a65e-4a65-a8b6-f2bc1b7f2249","html_url":"https://github.com/beastmp/biz-tracker-web","commit_stats":null,"previous_names":["beastmp/biz-tracker-web"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/beastmp/biz-tracker-web","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beastmp%2Fbiz-tracker-web","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beastmp%2Fbiz-tracker-web/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beastmp%2Fbiz-tracker-web/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beastmp%2Fbiz-tracker-web/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beastmp","download_url":"https://codeload.github.com/beastmp/biz-tracker-web/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beastmp%2Fbiz-tracker-web/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270982207,"owners_count":24679449,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["project-biz-tracker","react","web"],"created_at":"2025-04-05T17:19:08.424Z","updated_at":"2026-05-11T07:12:21.364Z","avatar_url":"https://github.com/beastmp.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BizTracker Web Application\n\n## Table of Contents\n\n1. [Introduction](#introduction)\n2. [Project Structure](#project-structure)\n3. [Key Technologies](#key-technologies)\n4. [Core Components](#core-components)\n5. [Feature Modules](#feature-modules)\n6. [Data Flow](#data-flow)\n7. [Setup and Configuration](#setup-and-configuration)\n8. [Extending the Application](#extending-the-application)\n\n## Introduction\n\nBizTracker is a comprehensive web application for small businesses to track inventory, sales, and purchases. It helps business owners maintain accurate inventory records, analyze product profitability, and monitor business transactions. The application features a modern React-based frontend with Material UI components for a responsive and intuitive user interface.\n\n## Project Structure\n\nThe application follows a feature-based structure:\n\n```\nbiz-tracker-web/\n├── src/\n│   ├── components/       # Shared UI components\n│   ├── context/          # React context providers\n│   ├── features/         # Feature modules\n│   │   ├── inventory/    # Inventory management\n│   │   ├── purchases/    # Purchase management\n│   │   └── sales/        # Sales management\n│   ├── hooks/            # Custom React hooks\n│   ├── types/            # TypeScript definitions\n│   └── utils/            # Utility functions\n├── public/               # Static assets\n├── index.html            # Entry HTML file\n├── vite.config.ts        # Vite configuration\n└── tsconfig.json         # TypeScript configuration\n```\n\n## Key Technologies\n\n- **React**: Frontend library for building user interfaces\n- **TypeScript**: Type-safe JavaScript\n- **Material UI**: Component library for consistent design\n- **React Router**: Navigation and routing\n- **React Query**: Data fetching, caching, and state management\n- **Vite**: Build tool and development server\n- **Firebase**: Hosting and backend services\n\n## Core Components\n\n### Application Layout\n\nThe `Layout` component (`src/components/Layout.tsx`) provides the overall structure of the application, including:\n\n- Responsive AppBar with navigation toggle\n- Side drawer navigation menu\n- Main content container\n- Theme toggle functionality\n\n```tsx\n// Main parts of the layout\n\u003cAppBar /\u003e         // Top navigation bar\n\u003cDrawer /\u003e         // Side navigation menu\n\u003cBox component=\"main\"\u003e // Main content area\n  \u003cOutlet /\u003e       // Route content is rendered here\n\u003c/Box\u003e\n```\n\n### Context Providers\n\n#### `AppContext` (`src/context/AppContext.tsx`)\n\nManages application-wide state including:\n- Theme switching (light/dark mode)\n- Default view mode for lists (grid/list)\n\n#### `SettingsContext` (`src/context/SettingsContext.tsx`)\n\nProvides user preferences and settings:\n- Low stock alert thresholds\n- Display preferences\n- Data management options\n\nThese settings are persisted in localStorage for a seamless user experience across sessions.\n\n### Error Handling\n\nThe `ErrorBoundary` component (`src/components/ErrorBoundary.tsx`) catches JavaScript errors in child components, preventing the entire application from crashing. It displays a user-friendly error message and provides options to recover.\n\n`ErrorFallback` (`src/components/ui/ErrorFallback.tsx`) renders a standardized error message with options to retry or navigate to the dashboard.\n\n## Feature Modules\n\n### Dashboard (`src/components/Dashboard.tsx`)\n\nThe dashboard provides an overview of business operations with:\n- Quick stats on inventory, sales, and purchases\n- Low stock alerts\n- Recent activity feeds\n- Quick action buttons\n\nIt connects with multiple data hooks:\n```tsx\nconst { data: items } = useItems();\nconst { data: sales } = useSales();\nconst { data: purchases } = usePurchases();\n```\n\n### Inventory Management\n\n#### Inventory List (`src/features/inventory/InventoryList.tsx`)\n\nThe inventory list shows all items with comprehensive filtering and viewing options:\n\n- Grid/list view toggle\n- Grouping by category or item type\n- Search functionality\n- Sorting options\n- Low stock indicators\n\nIt uses the settings context to respect user preferences:\n```tsx\nconst { lowStockAlertsEnabled, quantityThreshold, weightThresholds, defaultViewMode, defaultGroupBy } = useSettings();\n```\n\n#### Inventory Detail (`src/features/inventory/InventoryDetail.tsx`)\n\nDisplays comprehensive information about a single inventory item:\n- Basic item information\n- Stock levels and status\n- Pricing and cost information\n- Material relationships (components)\n- Product relationships (where used)\n- Quick actions\n\nIt allows breaking down generic material items into specific items through the `BreakdownItemsDialog`.\n\n#### Inventory Form (`src/features/inventory/InventoryForm.tsx`)\n\nA multi-section form for creating and editing inventory items:\n- Basic information (name, SKU, category)\n- Stock information with flexible tracking types (quantity, weight, length, area, volume)\n- Pricing information with markup calculation\n- Product composition (material components)\n- Image upload\n- Tags\n\nSupports complex inventory use cases like:\n- Pack-based purchasing\n- Multi-measurement tracking\n- Material-to-product relationships\n\n#### Profit Analysis (`src/features/inventory/InventoryProfitReport.tsx`)\n\nAnalyzes inventory profitability with:\n- Markup percentages by item\n- Profit margins\n- Category-based analysis\n- Visual charts and data tables\n\n### Sales and Purchases\n\nThe sales and purchases modules follow a similar pattern with list, detail, and form components:\n- `SalesList.tsx` / `PurchasesList.tsx`: Display all transactions\n- `SalesDetail.tsx` / `PurchaseDetail.tsx`: Show details of specific transactions\n- `SalesForm.tsx` / `PurchaseForm.tsx`: Create or edit transactions\n\nThese modules use dedicated hooks (`useSales`, `usePurchases`) to manage their specific data.\n\n### Special Components\n\n#### `CreateProductDialog` (`src/components/inventory/CreateProductDialog.tsx`)\n\nA dialog that streamlines the creation of products from existing materials:\n1. Select materials and quantities\n2. Set markup percentage or final price\n3. Calculate costs and pricing automatically\n4. Generate a new product with properly tracked material relationships\n\n#### `BreakdownItemsDialog` (`src/components/inventory/BreakdownItemsDialog.tsx`)\n\nEnables breaking down generic materials into specific derived items:\n1. Allocate quantities or weights from source material\n2. Generate appropriate SKUs and names\n3. Set specific properties for derived items\n4. Track relationships between source and derived items\n\n## Data Flow\n\nThe application uses React Query hooks for data fetching and state management:\n\n1. **Custom Hooks**: Domain-specific hooks fetch and manipulate data:\n   - `useItems()`: Inventory management\n   - `useSales()`: Sales transactions\n   - `usePurchases()`: Purchase orders\n\n2. **API Client**: Common utilities in `src/utils/apiClient.ts` handle HTTP requests\n\n3. **Context Providers**: Manage application state and user preferences\n\n4. **Component Integration**: Components consume hooks and context to render UI\n\n## Setup and Configuration\n\n### Environment Variables\n\nThe application uses environment variables for configuration (`.env.example`):\n```\nVITE_API_URL=http://localhost:3000\n```\n\n### Firebase Configuration\n\n`firebase.json` configures hosting and deployment:\n```json\n// Firebase hosting configuration\n```\n\n### TypeScript Configuration\n\nTwo TypeScript configurations manage different parts of the project:\n- `tsconfig.app.json`: Application code\n- `tsconfig.node.json`: Build scripts and configuration\n\n## Extending the Application\n\n### Adding New Features\n\n1. Create new components in the appropriate feature directory\n2. Add data hooks in `src/hooks/`\n3. Define types in `src/types/models.ts`\n4. Add routes in `src/routes.tsx`\n5. Update navigation in `src/components/Layout.tsx`\n\n### Customizing the UI\n\nThe application uses Material UI theming which can be extended in `src/context/AppContext.tsx`.\n\n### API Integration\n\nTo integrate with different backends:\n1. Modify the API client in `src/utils/apiClient.ts`\n2. Update environment variables in `.env`\n3. Adjust data hooks as needed\n\n## Expanding the ESLint configuration\n\nIf you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:\n\n```js\nexport default tseslint.config({\n  extends: [\n    // Remove ...tseslint.configs.recommended and replace with this\n    ...tseslint.configs.recommendedTypeChecked,\n    // Alternatively, use this for stricter rules\n    ...tseslint.configs.strictTypeChecked,\n    // Optionally, add this for stylistic rules\n    ...tseslint.configs.stylisticTypeChecked,\n  ],\n  languageOptions: {\n    // other options...\n    parserOptions: {\n      project: ['./tsconfig.node.json', './tsconfig.app.json'],\n      tsconfigRootDir: import.meta.dirname,\n    },\n  },\n})\n```\n\nYou can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:\n\n```js\n// eslint.config.js\nimport reactX from 'eslint-plugin-react-x'\nimport reactDom from 'eslint-plugin-react-dom'\n\nexport default tseslint.config({\n  plugins: {\n    // Add the react-x and react-dom plugins\n    'react-x': reactX,\n    'react-dom': reactDom,\n  },\n  rules: {\n    // other rules...\n    // Enable its recommended typescript rules\n    ...reactX.configs['recommended-typescript'].rules,\n    ...reactDom.configs.recommended.rules,\n  },\n})\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeastmp%2Fbiz-tracker-web","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeastmp%2Fbiz-tracker-web","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeastmp%2Fbiz-tracker-web/lists"}