# Project Overview - Trading & Inventory Management System
## Executive Summary
This is a comprehensive **multi-tenant trading and inventory management system** designed for businesses in Seychelles. The system handles inventory tracking, sales, purchases, accounting, financial reporting, and user management with granular permission controls. Built with modern technologies, the application supports multiple companies (tenants) with complete data isolation.
---
## Architecture Overview
The project follows a **microservices-oriented monolith** architecture with clear separation between backend API and frontend application:
- **Backend API** (`InvoiceApi`): FastAPI-based RESTful API service
- **Frontend Application** (`InvoiceApp`): Next.js-based single-page application
Both services are designed to work independently and can be deployed separately.
---
## Technology Stack
### Backend Stack (`InvoiceApi`)
#### Core Framework & Runtime
- **Python 3.x**
- **FastAPI 0.115.8** - Modern, fast web framework for building APIs
- **Uvicorn** - ASGI server for running FastAPI applications
- **Pydantic 2.10.6** - Data validation using Python type annotations
#### Database & ORM
- **PostgreSQL** - Primary relational database
- **SQLAlchemy 2.0.38** (Async) - Modern async ORM for database operations
- **Alembic 1.14.1** - Database migration tool
- **asyncpg** - High-performance async PostgreSQL driver
- **psycopg2/psycopg3** - PostgreSQL adapter (sync operations)
#### Authentication & Security
- **python-jose** - JWT token handling
- **bcrypt** - Password hashing
- **HTTPBearer** - Token-based authentication
- **CORS Middleware** - Cross-origin resource sharing
#### Additional Libraries
- **python-multipart** - File upload support
- **Pillow** - Image processing
- **python-dateutil** - Date/time utilities
- **pytz** - Timezone handling (Indian/Mahe timezone)
#### Development Tools
- **pytest** - Testing framework
- **pytest-asyncio** - Async test support
- **coverage** - Code coverage analysis
### Frontend Stack (`InvoiceApp`)
#### Core Framework
- **Next.js 15.4.4** - React framework with App Router
- **React 18.2.0** - UI library
- **TypeScript 5.x** - Type-safe JavaScript
#### UI Framework & Styling
- **Tailwind CSS 3.4.1** - Utility-first CSS framework
- **shadcn/ui** - High-quality component library built on Radix UI
- **Material-UI (MUI) 7.3.6** - Component library with icons
- **Radix UI** - Headless UI primitives (Dialog, Select, Toast, etc.)
- **Lucide React** - Icon library
- **react-icons** - Additional icon sets
#### State Management & Data Fetching
- **TanStack Query (React Query) 5.66.0** - Server state management and data fetching
- **React Context API** - Client-side state management:
- AuthContext - User authentication state
- PermissionContext - User permissions
- ThemeContext - UI theme (light/dark)
- CurrencyContext - Currency settings
- SidebarContext - Navigation state
- ToastContext - Notification system
- CategoryCacheContext - Category data caching
- AttributeCacheContext - Attribute data caching
- InitializationContext - App initialization state
#### Forms & Validation
- **React Hook Form 7.55.0** - Form state management
- **Zod 3.24.2** - Schema validation
- **@hookform/resolvers** - Zod resolver for React Hook Form
#### Data Visualization & Tables
- **TanStack Table 8.21.3** - Headless table library
- **react-window** - Virtualization for large lists
#### HTTP Client
- **Axios 1.7.9** - HTTP client with interceptors for authentication
#### Additional Utilities
- **date-fns 4.1.0** - Date formatting and manipulation
- **jwt-decode** - JWT token decoding
- **class-variance-authority** - Component variant management
- **clsx** & **tailwind-merge** - Conditional class names
- **react-hot-toast** - Toast notifications
- **react-select** & **react-select-async-paginate** - Advanced select components
- **qrcode.react** & **react-barcode** - QR code and barcode generation
- **@hello-pangea/dnd** - Drag and drop functionality
#### Development Tools
- **ESLint** - Code linting
- **Prettier** - Code formatting
- **TypeScript** - Type checking
---
## Key Features & Modules
### 1. Authentication & Authorization
- **JWT-based authentication** with access and refresh tokens
- **Multi-tenant user isolation** (company-based)
- **Role-based access control (RBAC)** with granular permissions
- **Permission system** supporting both role-level and user-level permissions
- **Token blacklisting** support (currently disabled, can be enabled)
- **Session tracking** for logged-in users
### 2. User Management
- User CRUD operations
- Role assignment and management
- Direct permission assignment
- User activity tracking
- User profile management with company association
### 3. Company Management
- Multi-company support
- Company information management
- Company logo upload and management
- Company activation/deactivation
### 4. Inventory Management
- **Products** - Product catalog with attributes and categories
- **Inventory Items** - SKU-level inventory tracking per warehouse
- **Warehouses** - Multi-warehouse support
- **Inventory Locations** - Location tracking within warehouses
- **Attributes & Attribute Details** - Flexible product attributes system
- **Colors** - Color management for products
### 5. Sales Management
- Sales orders creation and management
- Sales invoices
- Sales returns
- Customer relationship management
### 6. Purchase Management
- Purchase orders
- Purchase receiving
- Purchase returns (planned/implemented)
- Vendor management
### 7. Contact Management
- **Contacts** - Customer and vendor management
- **Contact Categories** - Flexible categorization system (supports multiple categories per contact)
- Address management
- Contact grouping
### 8. Accounting System
- **Chart of Accounts** - Hierarchical account structure
- **Ledger** - General ledger entries
- **Journal Entries** - Manual journal entry creation
- **Accounting Periods** - Period-based accounting
- **Automatic Accounting** - Integration with sales, purchases, and inventory
#### Account Types
- Assets (Current & Non-current)
- Liabilities (Current & Long-term)
- Equity
- Revenue
- Expenses
### 9. Financial Reporting
- **Trial Balance** - Account balances report
- **Profit & Loss Statement** - Income statement
- **Balance Sheet** - Financial position
- **Cash Flow Statement** - Cash flow analysis
- **Aging Reports** - Accounts receivable/payable aging
- **Daybook** - Daily transaction journal
- **Inventory Reports** - Stock reports
### 10. Shipping Management
- Shipping method configuration
- Shipping tracking
### 11. Audit & Logging
- **Audit Log** - Comprehensive audit trail of all data changes
- **User Activities** - User action tracking
- Timestamp tracking on all records
### 12. Settings Management
- System-wide settings
- Company-specific settings
- Currency configuration
- Form configuration
### 13. Geographic Data
- Countries, States, Cities management
- Pre-loaded geographic data support
### 14. Dashboard
- Company overview dashboard
- Key metrics and statistics
- Quick access to common operations
---
## Multi-Tenancy Architecture
The system implements **company-based multi-tenancy**:
- Every user belongs to a company (`company_id`)
- All data is scoped by `company_id` for isolation
- Users can only access data from their company
- Permissions are company-scoped
- Company activation status controls access
### Data Isolation Strategy
- All major tables include `company_id` foreign key
- API endpoints automatically filter by user's company
- Database queries include company_id filtering
- JWT tokens include company_id for validation
---
## Database Schema Highlights
### Core Tables
- `users` - User accounts
- `roles` - Role definitions (global)
- `permissions` - Permission definitions
- `role_permissions` - Role-permission mapping (company-scoped)
- `user_permissions` - Direct user permissions (company-scoped)
- `company_info` - Company information
### Business Tables
- `products` - Product catalog
- `inventory_items` - SKU-level inventory (per warehouse)
- `warehouses` - Warehouse definitions
- `inventory_locations` - Locations within warehouses
- `contacts` - Customers and vendors
- `contact_categories` - Contact categorization
- `purchase_orders` - Purchase orders
- `purchase_order_items` - Purchase line items
- `purchase_receives` - Purchase receiving records
- `sales_orders` - Sales orders
- `sales_order_items` - Sales line items
### Accounting Tables
- `ledger` - General ledger accounts
- `journal` - Journal entries
- `journal_items` - Journal entry line items
- `accounting_periods` - Accounting periods
### Supporting Tables
- `attributes` - Product attributes
- `attribute_details` - Attribute values
- `colors` - Color definitions
- `countries`, `states`, `cities` - Geographic data
- `user_activities` - User action logs
- `audit_log` - Audit trail
- `settings` - System settings
---
## API Architecture
### API Structure
- **Base URL**: `/api/v1`
- **Authentication**: Bearer token (JWT) in Authorization header
- **Response Format**: JSON
- **Error Handling**: Standardized error responses
### Module-Based Routing
Each feature module has its own router with CRUD endpoints:
- `/api/v1/users/`
- `/api/v1/products/`
- `/api/v1/inventory/`
- `/api/v1/sales/`
- `/api/v1/purchases/`
- `/api/v1/ledger/`
- `/api/v1/journal/`
- `/api/v1/reports/`
- And more...
### API Documentation
- **Swagger UI**: Available at `/docs`
- **ReDoc**: Available at `/redoc`
- OpenAPI 3.0 specification
---
## Frontend Architecture
### Routing Structure
- **App Router** (Next.js 15) - File-based routing
- **Route Groups**: `(auth)`, `(dashboard)` - Logical grouping
- **Protected Routes** - Middleware-based authentication
- **Dynamic Routes** - `[id]` for detail pages
### Component Organization
```
src/
├── app/ # Next.js app router pages
├── components/ # Reusable React components
│ ├── ui/ # shadcn/ui components
│ ├── common/ # Shared components
│ └── [module]/ # Feature-specific components
├── contexts/ # React Context providers
├── hooks/ # Custom React hooks
├── lib/ # Utility functions
├── types/ # TypeScript type definitions
├── utils/ # Helper functions
└── middleware/ # Route middleware
```
### State Management Pattern
1. **Server State**: TanStack Query for API data
2. **Client State**: React Context for global state
3. **Form State**: React Hook Form for form state
4. **URL State**: Next.js router for navigation state
---
## Security Features
### Authentication
- JWT access tokens (60-minute expiry)
- Refresh tokens (7-day expiry)
- Token validation on every request
- Token blacklisting capability
### Authorization
- Permission-based access control
- Role-based permissions
- Direct user permissions
- Admin permission bypass
- API-level permission checks
### Data Security
- Password hashing with bcrypt
- SQL injection prevention (ORM-based)
- CORS configuration
- HTTPS support in production
- Input validation with Pydantic/Zod
### Audit & Compliance
- Comprehensive audit logging
- User activity tracking
- Timestamp tracking on all records
- Company-based data isolation
---
## Deployment Configuration
### Backend Deployment
- **Server**: Linux-based server
- **Process Manager**: Systemd service (`ims-nextjs` - though name suggests frontend, likely used for backend too)
- **Reverse Proxy**: Nginx
- **Database**: PostgreSQL
- **Static Files**: Served via FastAPI StaticFiles
### Frontend Deployment
- **Server**: Linux-based server
- **Process Manager**: Systemd service (`ims-nextjs`)
- **Reverse Proxy**: Nginx
- **Build**: Next.js production build
- **Port**: 3001 (development), production port configurable
### Environment Configuration
- **Development**: Local development with hot reload
- **Production**: Optimized builds with multiple workers
- **Environment Variables**: `.env` files for configuration
### Domain Configuration
- **API Domain**: `api.n4sey.com`
- **App Domain**: `app.n4sey.com`
- **CORS**: Configured for production domains
---
## Timezone & Localization
- **Primary Timezone**: Indian/Mahe (Seychelles timezone)
- **UTC Storage**: All timestamps stored in UTC
- **Local Conversion**: Automatic conversion for display
- **Currency**: Configurable per company
---
## Development Workflow
### Backend Development
1. Database migrations via Alembic
2. Module-based development (models, schemas, services, routes)
3. Async/await pattern throughout
4. Type hints and Pydantic validation
5. API documentation auto-generated
### Frontend Development
1. Component-based development
2. TypeScript for type safety
3. React Query for server state
4. Form validation with Zod
5. Hot reload in development
### Database Migrations
- Alembic for version control
- Migration files in `alembic/versions/`
- Rollback support
- Seed data support
---
## Testing
### Backend Testing
- pytest for unit and integration tests
- pytest-asyncio for async tests
- Coverage reporting
- Mock support for external dependencies
### Frontend Testing
- Testing infrastructure ready (can be extended)
- TypeScript provides compile-time type checking
---
## File Structure Highlights
### Backend (`InvoiceApi/`)
```
app/
├── core/ # Core functionality (auth, database, config)
├── modules/ # Feature modules
│ ├── users/ # User management
│ ├── products/ # Product management
│ ├── inventory/ # Inventory management
│ ├── sales/ # Sales management
│ ├── purchases/ # Purchase management
│ ├── ledger/ # Accounting ledger
│ ├── journal/ # Journal entries
│ ├── reports/ # Financial reports
│ └── ...
├── main.py # FastAPI application entry point
alembic/ # Database migrations
media/ # File uploads (logos, product images)
```
### Frontend (`InvoiceApp/`)
```
src/
├── app/ # Next.js pages and routes
│ ├── (auth)/ # Authentication pages
│ └── (dashboard)/ # Main application pages
├── components/ # React components
├── contexts/ # Context providers
├── hooks/ # Custom hooks
├── lib/ # Libraries and utilities
├── types/ # TypeScript types
└── utils/ # Utility functions
```
---
## Current Status & Future Enhancements
### Implemented Features
✅ Multi-tenant architecture
✅ User authentication and authorization
✅ Product and inventory management
✅ Sales and purchase management
✅ Accounting system (ledger, journal)
✅ Financial reporting
✅ Contact management
✅ Audit logging
✅ Dashboard
### Planned/In Progress
- Asset tracking system (as per Plan.md)
- Enhanced purchase returns
- Advanced reporting features
- Asset maintenance tracking
- Asset depreciation
---
## Key Configuration Files
### Backend
- `requirements.txt` - Python dependencies
- `alembic.ini` - Alembic configuration
- `.env` - Environment variables
- `app/core/config.py` - Application settings
### Frontend
- `package.json` - Node.js dependencies
- `next.config.ts` - Next.js configuration
- `tailwind.config.ts` - Tailwind CSS configuration
- `tsconfig.json` - TypeScript configuration
---
## Documentation
The project includes several documentation files:
- `Plan.md` - Implementation plan for asset tracking
- `MULTI_TENANCY_FILTERING.md` - Multi-tenancy documentation
- `ACCOUNTING_IMPLEMENTATION_SUMMARY.md` - Accounting system details
- `CLI_COMMANDS.md` - CLI command reference
- Various implementation guides for specific features
---
## Dependencies Summary
### Backend Key Dependencies
- FastAPI ecosystem (FastAPI, Uvicorn, Starlette)
- SQLAlchemy (async ORM)
- PostgreSQL drivers (asyncpg, psycopg)
- Authentication (python-jose, bcrypt)
- Data validation (Pydantic)
- File handling (Pillow, python-multipart)
### Frontend Key Dependencies
- Next.js & React ecosystem
- UI libraries (shadcn/ui, MUI, Radix UI)
- Data fetching (TanStack Query)
- Forms (React Hook Form, Zod)
- Styling (Tailwind CSS)
- Utilities (Axios, date-fns, jwt-decode)
---
## Performance Considerations
- **Async operations** throughout backend for better concurrency
- **Database connection pooling** configured
- **Query optimization** with proper indexing
- **Pagination** implemented for large datasets
- **React Query caching** for efficient data fetching
- **Virtual scrolling** for large lists (react-window)
- **Code splitting** via Next.js automatic code splitting
---
## Conclusion
This is a comprehensive, production-ready trading and inventory management system built with modern technologies. The architecture supports scalability, maintainability, and security with a clear separation of concerns between backend API and frontend application. The multi-tenant design allows multiple companies to use the system while maintaining complete data isolation.