🚢 SHIPWISE - COMPREHENSIVE PROJECT ANALYSIS

Analysis Date: April 29, 2026
Analyst: Senior SaaS Architect Review
Project Type: Multi-tenant SaaS Logistics Platform

📋 EXECUTIVE SUMMARY

Shipwise is a multi-tenant SaaS logistics and workforce shipment management platform designed to help logistics companies manage shipments, employees, field operations, delivery workflows, delays, and business performance through web and mobile platforms.

Current Status: 🟡 FUNCTIONAL PROTOTYPE - Core architecture in place, but incomplete features and missing production-grade components.

🏗️ ARCHITECTURE OVERVIEW

Technology Stack

Frontend Web Application

Framework: Next.js 14 (React 18)
Styling: Tailwind CSS + Radix UI components
State Management: React Context API (AuthContext)
Authentication: Supabase Auth (Google OAuth)
API Client: Custom fetch wrapper with JWT bearer tokens
Build Tool: Next.js built-in (Webpack/Turbopack)

Mobile Application

Framework: React Native + Expo (~50.0.0)
Navigation: React Navigation (Stack + Bottom Tabs)
State: React Context (AuthContext, LanguageContext)
Storage: AsyncStorage
Status: ⚠️ DEMO MODE - Hardcoded data, no real API integration

Backend

Primary: Supabase (Backend-as-a-Service)
- PostgreSQL database
- Row Level Security (RLS)
- REST API auto-generated
- Real-time subscriptions (not utilized yet)
Secondary: Express.js server (minimal, mostly unused)
- Located in /backend folder
- Only has demo routes
- NOT integrated with frontend

Database

Provider: Supabase PostgreSQL
Schema Status: ⚠️ PARTIALLY MIGRATED
Migration Files: Legacy files in database/legacy/, new RBAC schema in 006_rbac_audit_notifications.sql

👥 USER ROLES & PERMISSIONS

Role Hierarchy (Implemented)

┌─────────────────────────────────────────────────────────┐
│                    SUPER ADMIN                          │
│  - Platform owner                                       │
│  - Manages all tenants/organizations                    │
│  - Approves organization requests                       │
│  - Views audit logs across platform                     │
└─────────────────────────────────────────────────────────┘
                           │
        ┌──────────────────┴──────────────────┐
        │                                     │
┌───────▼────────┐                  ┌─────────▼────────┐
│   HR (Tenant   │                  │   STAFF (Web)    │
│     Admin)     │                  │                  │
│ - Org profile  │                  │ - Shipments CRUD │
│ - User mgmt    │                  │ - Carriers CRUD  │
│ - Role assign  │                  │ - Incidents CRUD │
└────────────────┘                  │ - Goods view     │
                                    └──────────────────┘
        │
        │
┌───────▼────────┐
│ MANAGER (Mobile)│
│ - View only     │
│ - Field ops     │
│ - Shipment track│
└─────────────────┘

Permission System (RBAC)

Location: frontend-web/lib/rbac.ts

Implemented Permissions:

✅ SUPERADMIN_PORTAL_ACCESS
✅ HR_PORTAL_ACCESS
✅ OPERATIONS_PORTAL_ACCESS
✅ USERS_MANAGE
✅ SHIPMENTS_READ / SHIPMENTS_WRITE
✅ CARRIERS_READ / CARRIERS_WRITE
✅ INCIDENTS_READ / INCIDENTS_WRITE
✅ GOODS_READ
✅ AUDIT_LOGS_READ
✅ NOTIFICATIONS_READ
✅ ORGANIZATION_REQUESTS_SUBMIT / DECIDE

Permission Enforcement:

✅ Client-side: usePagePermission hook with auto-redirect
✅ Server-side: requireApiPermission middleware
✅ Database: Row Level Security (RLS) policies

🗄️ DATABASE SCHEMA

Current Tables (Expected)

Based on code analysis, the following tables should exist:

Core Tables

users - User accounts with organization membership
- user_id (UUID, FK to auth.users)
- organization_id (text)
- email (text)
- role (text: 'hr' | 'manager' | 'staff')
- is_super_admin (boolean)
- is__active (boolean)
- created_at (timestamptz)
organizations - Tenant/company records
- organization_id (text, PK)
- name (text)
- industry_type (text)
- status (text)
- created_at (timestamptz)
shipments - Shipment tracking
- shipment_id (text, PK)
- organization_id (text, FK)
- origin_country (text)
- destination_country (text)
- carrier_id (text, FK)
- status (text: 'pending' | 'in_transit' | 'delivered' | 'delayed' | 'cancelled')
- planned_eta (timestamptz)
- actual_eta (timestamptz)
- created_by (UUID)
- created_at (timestamptz)
carriers - Shipping carriers
- carrier_id (text, PK)
- organization_id (text, FK)
- name (text)
- relability_score (numeric) ⚠️ Typo: should be "reliability"
- average_delay_days (numeric)
- created_at (timestamptz)
incidents - Shipment incidents
- incident_id (UUID, PK)
- organization_id (text, FK)
- shipment_id (text, FK)
- incident_type (text)
- severity (text: 'low' | 'medium' | 'high')
- description (text)
- reported_at (timestamptz)
- created_at (timestamptz)
goods - Goods/products
- good_id (UUID, PK)
- organization_id (text, FK)
- name (text)
- category (text)
- created_at (timestamptz)

System Tables (from 006_rbac_audit_notifications.sql)

audit_logs - Audit trail
- audit_log_id (UUID, PK)
- organization_id (text)
- actor_user_id (UUID)
- action (text)
- target_type (text)
- target_id (text)
- metadata (jsonb)
- created_at (timestamptz)
notification_outbox - Notification queue
- notification_id (UUID, PK)
- organization_id (text)
- recipient_user_id (UUID)
- recipient_email (text)
- type (text)
- title (text)
- body (text)
- channels (text[])
- status (text: 'pending' | 'sent' | 'failed')
- sent_at (timestamptz)
- created_at (timestamptz)
domain_events - Event sourcing queue
- event_id (UUID, PK)
- organization_id (text)
- actor_user_id (UUID)
- event_type (text)
- aggregate_type (text)
- aggregate_id (text)
- payload (jsonb)
- status (text: 'pending' | 'processed' | 'failed')
- processed_at (timestamptz)
- created_at (timestamptz)
organization_requests - Onboarding requests
- request_id (UUID, PK)
- requester_user_id (UUID)
- requester_email (text)
- company_name (text)
- industry_type (text)
- status (text: 'pending' | 'approved' | 'rejected')
- created_at (timestamptz)

⚠️ CRITICAL DATABASE ISSUES

Migration Status Unknown
- Legacy migration files exist but may not have been run
- New RBAC schema (006) exists but unclear if applied
- ACTION REQUIRED: Verify which tables actually exist in Supabase
No Migration Tracking
- No schema_migrations table
- No version control for database changes
- Risk of inconsistent state across environments
RLS Policies
- Defined in SQL but unclear if active
- Need verification of policy enforcement

🔐 AUTHENTICATION & AUTHORIZATION

Authentication Flow

1. User clicks "Sign in with Google" → /auth
2. Supabase redirects to Google OAuth
3. Google callback → /auth/callback
4. Supabase creates session (JWT)
5. Frontend loads user profile from `users` table
6. Frontend loads organization from `organizations` table
7. Redirect to /post-login
8. Role-based redirect to appropriate portal

Session Management

✅ PKCE flow enabled
✅ Session persistence in browser
✅ Auto-refresh tokens
✅ JWT bearer tokens for API calls

Authorization Layers

Client-Side (React)
- usePagePermission hook
- Auto-redirects unauthorized users
- Hides UI elements based on permissions
API Layer (Next.js API Routes)
- requireApiPermission middleware
- Validates JWT token
- Checks user permissions
- Enforces organization isolation
Database Layer (Supabase RLS)
- Row-level security policies
- Organization-based data isolation
- Helper functions: current_user_role(), current_user_is_super_admin()

📱 FRONTEND WEB APPLICATION

Page Structure

/auth                    → Google OAuth login
/auth/callback           → OAuth callback handler
/post-login              → Role-based routing hub
/request-access          → Organization onboarding request

# Super Admin Portal
/superadmin/requests     → Approve/reject org requests
/superadmin/audit-logs   → Platform-wide audit logs

# HR Portal
/hr                      → Organization profile management
/usermanagement          → User CRUD, role assignment

# Operations Portal (Staff/Manager)
/dashboard               → KPIs, shipments, incidents overview
/shipments               → Shipment list with filters
/carriers                → Carrier management
/goods                   → Goods catalog
/incidents               → Incident tracking
/notifications           → User notifications (page exists)

API Routes (Next.js)

/api/shipments           → GET, POST, PATCH (CRUD)
/api/carriers            → GET
/api/goods               → GET
/api/incidents           → GET
/api/users               → GET, POST, PATCH (HR only)
/api/audit-logs          → GET (Super Admin / HR)
/api/notifications       → GET
/api/organization-requests → GET, POST
/api/organization-requests/[id]/decision → POST (approve/reject)
/api/organizations/me    → GET, PATCH (current org profile)
/api/events/process      → POST (domain event processor)
/api/notifications/dispatch → POST (notification sender)

Component Architecture

Shared Components:

AppLayout - Main layout with sidebar navigation
ShipwiseLogo - Branded logo component
StatusBadge - Status indicator (pending, in_transit, etc.)
StatCard - Dashboard metric card
Radix UI primitives (Dialog, Select, Table, etc.)

Contexts:

AuthContext - User session, login/logout, profile loading
(No global state management beyond Context API)

Styling

Tailwind CSS utility classes
Custom color palette (cyan/blue theme)
Glassmorphism effects (backdrop-blur)
Responsive design (mobile-first)

📱 MOBILE APPLICATION

Current Status: ⚠️ DEMO MODE

Screens Implemented:

✅ SignInScreen (hardcoded demo login)
✅ DashboardScreen (mock data)
✅ ShipmentListScreen
✅ ShipmentDetailScreen
✅ AnalyticsScreen
✅ AlertsScreen
✅ ProfileScreen
✅ EditProfileScreen
✅ ChangePasswordScreen
✅ AIAssistantScreen

Critical Issues:

No Real Authentication
- Uses AsyncStorage with hardcoded demo user
- No Supabase integration
- No JWT tokens
No API Integration
- Mock services: shipmentService, mlService
- No connection to backend
- Data is static/hardcoded
No Supabase SDK
- Missing @supabase/supabase-js dependency
- Would need React Native-compatible setup

What Works:

✅ Navigation structure
✅ UI/UX design
✅ Component architecture
✅ Theming system

What's Missing:

❌ Real authentication
❌ API calls to Supabase
❌ Real-time updates
❌ Push notifications
❌ Offline support
❌ Error handling

🔍 MULTI-TENANCY ARCHITECTURE

Tenant Isolation Strategy

Approach: Shared Database, Row-Level Isolation

-- Every data table has organization_id
CREATE TABLE shipments (
  shipment_id text PRIMARY KEY,
  organization_id text NOT NULL,  -- Tenant discriminator
  ...
);

-- RLS policy enforces isolation
CREATE POLICY shipments_select_policy ON shipments
FOR SELECT USING (
  organization_id IN (
    SELECT u.organization_id
    FROM users u
    WHERE u.user_id = auth.uid()
  )
);

Tenant Onboarding Flow

User signs in with Google (no users record yet)
Redirected to /request-access
Submits organization request → organization_requests table
Super Admin reviews at /superadmin/requests
On approval:
- Create organizations record
- Create users record with role='hr'
- Requester becomes HR owner
HR can now add users to their organization

Data Isolation Verification

✅ API Layer: All queries filter by organization_id ✅ Database Layer: RLS policies enforce isolation ⚠️ Super Admin: Can bypass isolation (by design)

✅ WHAT CURRENTLY EXISTS

Fully Implemented

✅ Google OAuth Authentication
- Sign in/sign out
- Session management
- Token refresh
✅ Role-Based Access Control (RBAC)
- 4 roles: superadmin, hr, manager, staff
- Permission system
- Client + server enforcement
✅ Multi-Tenant Architecture
- Organization isolation
- RLS policies
- Tenant onboarding flow
✅ Super Admin Portal
- Organization request approval
- Audit log viewing
✅ HR Portal
- Organization profile management
- User management (CRUD)
- Role assignment
✅ Operations Portal (Staff)
- Dashboard with KPIs
- Shipment management (CRUD)
- Carrier viewing
- Incident viewing
- Goods viewing
✅ Audit Logging
- User actions tracked
- Organization-scoped
- Queryable by HR/Super Admin
✅ Domain Events
- Event sourcing pattern
- Async processing ready
- Event queue table
✅ Notification System (Infrastructure)
- Notification outbox table
- Multi-channel support (in_app, email)
- Status tracking
✅ Modern UI/UX
- Tailwind CSS
- Radix UI components
- Responsive design
- Glassmorphism effects

❌ WHAT IS INCOMPLETE

Critical Missing Features

❌ Database Migration Verification
- Unknown if tables actually exist in Supabase
- No migration tracking system
- BLOCKER: App may not work without proper schema
❌ Mobile App Integration
- No real authentication
- No API calls
- Completely disconnected from backend
- BLOCKER: Mobile app is non-functional
❌ Notification Delivery
- Outbox table exists
- No email sending service
- No in-app notification UI
- No push notifications
❌ Domain Event Processing
- Events are written to queue
- No background processor
- No event handlers
- Events never get processed
❌ Manager Role Functionality
- Role exists in RBAC
- No dedicated manager portal
- No mobile app integration
- Unclear what managers should do
❌ Carrier Management (Write)
- Can view carriers
- No create/update/delete UI
- API endpoint missing
❌ Goods Management (Write)
- Can view goods
- No create/update/delete UI
- API endpoint missing
❌ Incident Management (Write)
- Can view incidents
- No create/update/delete UI
- API endpoint missing
❌ Real-Time Updates
- Supabase supports real-time
- Not implemented anywhere
- Manual refresh required
❌ Search & Filtering
- Basic search on shipments page
- No advanced filters
- No full-text search
❌ Analytics & Reporting
- Basic dashboard charts
- No export functionality
- No custom reports
- No date range filters
❌ File Uploads
- No document attachments
- No proof of delivery
- No carrier contracts
❌ Email Notifications
- No email service integration
- No email templates
- No notification preferences
❌ User Profile Management
- Can't update own profile
- No password change (OAuth only)
- No profile picture
❌ Organization Settings
- Basic profile editing
- No branding customization
- No feature flags
- No subscription management
❌ API Documentation
- No OpenAPI/Swagger
- No API versioning
- No rate limiting
❌ Error Handling
- Basic try/catch
- No error boundaries
- No user-friendly error messages
- No error reporting service
❌ Testing
- Vitest configured but no tests
- No E2E tests
- No API tests
❌ Deployment Pipeline
- No CI/CD
- No environment management
- No staging environment
❌ Monitoring & Observability
- reportError function exists but not implemented
- No logging service
- No performance monitoring
- No uptime monitoring

🐛 BUGS & ISSUES IDENTIFIED

High Priority

🐛 Typo in Database Schema
- carriers.relability_score should be reliability_score
- Used throughout codebase
🐛 Inconsistent User Table Field
- is__active (double underscore) should be is_active
- Typo in schema
🐛 Missing Error Handling
- Many API calls have .catch(console.error)
- No user feedback on errors
🐛 No Loading States
- Some pages show empty state while loading
- Confusing UX
🐛 Hardcoded Supabase Project
- .env has specific project URL
- Should be in .env.example only

Medium Priority

🐛 Unused Backend Server
- Express server in /backend folder
- Not integrated with frontend
- Confusing architecture
🐛 Mobile App Completely Broken
- Demo mode only
- No real functionality
🐛 No Input Validation
- Forms accept any input
- No client-side validation
- Relies on database constraints
🐛 No Pagination
- All queries fetch all records
- Will break with large datasets
🐛 No Optimistic Updates
- All mutations require server round-trip
- Slow UX

Low Priority

🐛 Inconsistent Naming
- Some files use PascalCase, others camelCase
- Mix of .tsx and .ts extensions
🐛 Dead Code
- Legacy migration files
- Unused components
🐛 No TypeScript Strict Mode
- Many any types
- Weak type safety

🏆 CODE QUALITY ASSESSMENT

Strengths

✅ Modern Tech Stack

Next.js 14, React 18, TypeScript
Supabase (excellent choice for SaaS)
Tailwind CSS + Radix UI

✅ Clean Architecture

Separation of concerns
Reusable components
Context-based state management

✅ Security-First

JWT authentication
RLS policies
Permission-based access control

✅ Scalable Multi-Tenancy

Proper tenant isolation
Organization-scoped queries
Super admin oversight

✅ Professional UI/UX

Modern design
Consistent styling
Responsive layout

Weaknesses

❌ Incomplete Features

Many half-implemented modules
Mobile app is non-functional
Missing CRUD operations

❌ No Testing

Zero test coverage
No CI/CD
High risk of regressions

❌ Poor Error Handling

Silent failures
No user feedback
No error tracking

❌ No Documentation

No API docs
No setup guide (beyond basic)
No architecture diagrams

❌ Technical Debt

Typos in schema
Unused code
Inconsistent patterns

🎯 RECOMMENDED NEXT STEPS

Phase 1: Foundation (Week 1-2)

Priority: CRITICAL

✅ Verify Database Schema
- Connect to Supabase dashboard
- Check which tables exist
- Run missing migrations
- Fix typos (relability_score, is__active)
✅ Create Migration System
- Add schema_migrations table
- Version all migrations
- Document migration process
✅ Fix Critical Bugs
- Rename relability_score → reliability_score
- Rename is__active → is_active
- Update all references
✅ Add Error Handling
- Implement reportError function
- Add error boundaries
- Show user-friendly error messages
✅ Add Loading States
- Skeleton loaders
- Spinner components
- Disable buttons during mutations

Phase 2: Complete Core Features (Week 3-4)

Priority: HIGH

✅ Implement Missing CRUD
- Carriers: Create, Update, Delete
- Goods: Create, Update, Delete
- Incidents: Create, Update, Delete
✅ Add Pagination
- Implement cursor-based pagination
- Add page size controls
- Optimize large queries
✅ Implement Notifications
- In-app notification UI
- Email service integration (SendGrid/Resend)
- Notification preferences
✅ Domain Event Processing
- Background worker (Supabase Edge Functions or separate service)
- Event handlers
- Retry logic
✅ Manager Portal
- Define manager workflows
- Create manager-specific pages
- Mobile app integration plan

Phase 3: Mobile App (Week 5-6)

Priority: HIGH

✅ Integrate Supabase in Mobile
- Add @supabase/supabase-js
- Implement real authentication
- Connect to API
✅ Replace Mock Data
- Remove hardcoded services
- Fetch real data from Supabase
- Handle loading/error states
✅ Add Offline Support
- Cache data locally
- Queue mutations
- Sync when online
✅ Push Notifications
- Expo push notifications
- Notification permissions
- Deep linking

Phase 4: Polish & Production (Week 7-8)

Priority: MEDIUM

✅ Add Testing
- Unit tests for utilities
- Integration tests for API routes
- E2E tests for critical flows
✅ Implement Analytics
- Export to CSV/Excel
- Custom date ranges
- Advanced filtering
✅ File Uploads
- Supabase Storage integration
- Document attachments
- Image optimization
✅ Real-Time Updates
- Supabase subscriptions
- Live dashboard updates
- Collaborative editing
✅ Monitoring & Logging
- Sentry for error tracking
- LogRocket for session replay
- Supabase logs
✅ CI/CD Pipeline
- GitHub Actions
- Automated testing
- Staging + production environments

Phase 5: Enterprise Features (Week 9-12)

Priority: LOW

✅ Advanced RBAC
- Custom roles
- Fine-grained permissions
- Role templates
✅ Subscription Management
- Stripe integration
- Plan tiers
- Usage limits
✅ White-Labeling
- Custom branding
- Custom domains
- Theme customization
✅ API for Third-Party Integration
- REST API documentation
- API keys
- Webhooks
✅ Advanced Analytics
- BI dashboard
- Predictive analytics
- ML-powered insights

📊 PROJECT HEALTH SCORE

Category	Score	Notes
Architecture	8/10	Solid multi-tenant design, good separation of concerns
Code Quality	6/10	Clean but incomplete, many `any` types, no tests
Security	8/10	Strong auth, RLS policies, permission system
Completeness	4/10	Many half-implemented features, mobile app broken
Scalability	7/10	Good foundation, but needs pagination, caching
UX/UI	8/10	Modern, professional design, responsive
Documentation	3/10	Minimal docs, no API reference
Testing	1/10	No tests written
Production Readiness	3/10	Not ready for production use

Overall Score: 5.3/10 - FUNCTIONAL PROTOTYPE

🚀 DEPLOYMENT READINESS

What's Ready

✅ Frontend web app (Next.js) ✅ Supabase backend ✅ Authentication flow ✅ Basic RBAC

What's NOT Ready

❌ Database schema verification ❌ Mobile app ❌ Notification delivery ❌ Event processing ❌ Error monitoring ❌ Testing ❌ CI/CD

Recommended Deployment Strategy

Staging Environment First
- Deploy to Vercel (frontend)
- Separate Supabase project
- Test all flows
Beta Testing
- Invite 2-3 pilot organizations
- Gather feedback
- Fix critical bugs
Production Launch
- Only after Phase 1-2 complete
- Monitoring in place
- Support plan ready

💡 ARCHITECTURAL RECOMMENDATIONS

Keep

✅ Supabase as primary backend ✅ Next.js for web frontend ✅ React Native for mobile ✅ Multi-tenant architecture ✅ RBAC permission system

Remove

❌ Unused Express backend in /backend ❌ Legacy migration files ❌ Hardcoded demo data in mobile

Add

➕ Background job processor (Supabase Edge Functions or BullMQ) ➕ Email service (Resend or SendGrid) ➕ Error tracking (Sentry) ➕ Analytics (PostHog or Mixpanel) ➕ File storage (Supabase Storage)

Improve

🔧 TypeScript strict mode 🔧 Input validation (Zod schemas) 🔧 API response types 🔧 Error handling patterns 🔧 Loading state management

📝 CONCLUSION

Shipwise is a well-architected SaaS platform with a solid foundation, but it's currently in a prototype stage with many incomplete features. The core multi-tenant architecture, authentication, and RBAC systems are professionally implemented, but critical gaps exist in:

Database schema verification (highest priority)
Mobile app integration (completely broken)
Notification and event processing (infrastructure exists but not functional)
Testing and monitoring (non-existent)

Recommendation: Do NOT deploy to production yet. Complete Phase 1-2 (4-6 weeks) before considering beta testing. The platform has excellent potential but needs focused development to reach production-grade quality.

Estimated Time to Production-Ready: 8-12 weeks with a dedicated team.

Next Immediate Action: Verify database schema in Supabase dashboard and run missing migrations.

FilesExpand file tree

PROJECT_ANALYSIS.md

Latest commit

History