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.