🧾 GST Invoice & Shipping Manager for Shopify

A comprehensive GST-compliant invoicing and shipping management solution for Indian Shopify merchants. Built from scratch following Shopify's latest development guidelines and best practices.

🎯 Features

✅ Core Features

🧾 GST Invoice Management

GST-Compliant Invoices: Automatic CGST/SGST/IGST calculations based on place of supply
HSN/SAC Code Support: Product classification for tax compliance
Invoice Templates: Professional PDF generation with company branding
Sequential Numbering: Configurable invoice numbering system
Multi-State Support: Handles inter-state and intra-state transactions
Reverse Charge: Support for reverse charge mechanism

👥 Customer Management

Customer Database: Complete customer information with GSTIN validation
Address Management: Multiple addresses per customer
Business Information: B2B and B2C customer classification
Shopify Integration: Automatic customer sync from orders

📦 Shipping Label System

Label Generation: Professional shipping labels with tracking
Barcode/QR Codes: Integrated tracking codes
Multi-Courier Support: Support for various courier services
Package Management: Weight, dimensions, and package type tracking

⚙️ Settings & Configuration

Company Setup: GSTIN, address, and business information
Tax Configuration: Default GST rates and tax settings
Invoice Customization: Prefixes, numbering, and templates
Compliance Settings: GST compliance parameters

🛠 Technology Stack

Frontend: React 18 + Remix Framework + TypeScript
UI Framework: Shopify Polaris (Official Design System)
Backend: Node.js with Remix Server
Database: SQLite (Development) / PostgreSQL (Production)
ORM: Prisma
Authentication: Shopify App Bridge + OAuth
API: Shopify GraphQL Admin API
Deployment: Vercel / Railway / Heroku

🚀 Quick Start

Prerequisites

Node.js 18+
npm or yarn
Shopify Partner Account
Shopify CLI

Installation

Clone the repository

git clone <repository-url>
cd gst-invoice-shipping-manager

Install dependencies
```
npm install
```

Set up environment variables

cp .env.example .env
# Edit .env with your Shopify app credentials

Set up database
```
npx prisma generate
npx prisma db push
```
Start development server
```
npm run dev
```

Environment Variables

# Shopify App Configuration
SHOPIFY_API_KEY=your_api_key
SHOPIFY_API_SECRET=your_api_secret
SCOPES=write_orders,read_orders,write_customers,read_customers,write_products,read_products
SHOPIFY_APP_URL=https://your-app-domain.com

# Database
DATABASE_URL=file:./dev.db

# Session Storage
SESSION_SECRET=your_session_secret

# GST Configuration
DEFAULT_GST_RATE=18
COMPANY_GSTIN=your_company_gstin
COMPANY_NAME=Your Company Name

📊 Database Schema

The app uses a comprehensive database schema with the following models:

Session: Shopify authentication and session management
Invoice: GST-compliant invoice data with tax calculations
Customer: Customer information with GSTIN support
ShippingLabel: Shipping label and tracking information
AppSettings: App configuration and company settings
Subscription: Billing and subscription management
WebhookLog: Webhook processing and debugging

🏗 Project Structure

app/
├── components/           # Reusable React components
├── models/              # Database models and queries
├── routes/              # Remix routes (pages and API)
│   ├── app._index.tsx   # Dashboard
│   ├── app.invoices/    # Invoice management
│   ├── app.customers/   # Customer management
│   ├── app.settings.tsx # App configuration
│   └── webhooks/        # Shopify webhook handlers
├── services/            # Business logic services
├── utils/               # Utility functions
│   └── gst.server.ts    # GST calculation utilities
└── shopify.server.ts    # Shopify app configuration

🇮🇳 GST Compliance Features

Tax Calculations

CGST + SGST: For intra-state transactions (same state)
IGST: For inter-state transactions (different states)
Place of Supply: Automatic determination based on delivery address
Tax Rates: Support for 0%, 5%, 12%, 18%, and 28% GST rates

Invoice Requirements

Sequential Numbering: Continuous invoice numbering
GSTIN Validation: 15-digit GSTIN format validation
HSN/SAC Codes: Product classification codes
Reverse Charge: Support for reverse charge mechanism
Currency Format: Indian Rupee formatting with words

Compliance Reports

Tax Summary: CGST, SGST, IGST breakdowns
Customer Reports: B2B and B2C transaction summaries
Period Reports: Monthly and quarterly tax reports

🔧 Development

Available Scripts

npm run dev          # Start development server
npm run build        # Build for production
npm run start        # Start production server
npm run lint         # Run ESLint
npm test             # Run tests
npm run setup        # Setup database

Adding New Features

Database Changes: Update prisma/schema.prisma
Routes: Add new routes in app/routes/
Components: Create reusable components in app/components/
Utilities: Add helper functions in app/utils/

📱 Shopify Integration

App Surfaces

Admin Dashboard: Embedded app pages in Shopify Admin
Navigation: Custom navigation menu in Shopify Admin
Settings: Configuration pages for app setup

Webhooks

Orders Created: Automatic customer and invoice data sync
Orders Updated: Real-time order status updates
Customers Created/Updated: Customer information sync
App Uninstalled: Cleanup on app uninstallation

GraphQL Integration

Orders API: Fetch order details and line items
Customers API: Customer information and addresses
Products API: Product details and HSN codes

🔐 Security & Privacy

Data Protection

Shopify OAuth: Official authentication flow
Session Management: Secure session storage with Prisma
Data Encryption: Sensitive data protection
GDPR Compliance: Privacy regulation compliance

API Security

Rate Limiting: API request rate limiting
Input Validation: All user inputs validated
SQL Injection Protection: Prisma ORM protection
XSS Prevention: React built-in XSS protection

📈 Performance

Optimization

Code Splitting: Automatic code splitting with Remix
Lazy Loading: Component lazy loading
Database Indexing: Optimized database queries
Caching: Response caching for better performance

Monitoring

Error Tracking: Comprehensive error handling
Performance Metrics: App performance monitoring
Webhook Logging: Webhook processing logs

🚀 Deployment

Production Deployment

Build the app
```
npm run build
```

Set up production database

DATABASE_URL=postgresql://... npx prisma db push

Deploy to platform

# Vercel
vercel --prod

# Railway
railway up

# Heroku
git push heroku main

Environment Setup

Database: PostgreSQL for production
File Storage: Cloud storage for invoice PDFs
Email Service: SMTP or SendGrid for notifications
Monitoring: Error tracking and performance monitoring

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Documentation: Wiki
Issues: GitHub Issues
Discussions: GitHub Discussions

🎯 Roadmap

Phase 1 (Current) ✅

Phase 2 (Next)

Phase 3 (Future)

🏆 Features

✅ Modern Architecture: Built with latest Shopify development standards
✅ GST Compliance: 100% compliant with Indian GST regulations
✅ Professional UI: Shopify Polaris design system
✅ Real-time Sync: Webhook-based data synchronization
✅ Scalable: Built for high-volume operations
✅ Secure: Enterprise-level security measures

Made with ❤️ for Indian Shopify merchants

Simplifying GST compliance and shipping management, one invoice at a time.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
app		app
prisma		prisma
.gitignore		.gitignore
DEPLOYMENT.md		DEPLOYMENT.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
shopify.app.toml		shopify.app.toml
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

r2w34/ShopifyGST

Folders and files

Latest commit

History

Repository files navigation