kasapro

Arsitektur Teknis

Overview arsitektur teknis Kasapro untuk developers dan power users.

---

System Architecture Overview

High-Level Architecture

graph TB
    subgraph Client["Client Layer"]
        Browser["Web Browser"]
        Mobile["Mobile Browser<br/>(PWA)"]
    end
    
    subgraph Nginx["Nginx Reverse Proxy"]
        SSL["SSL/TLS<br/>Termination"]
        Routing["Request Routing"]
    end
    
    subgraph Application["Application Layer"]
        Frontend["Frontend<br/>(Next.js)"]
        Backend["Backend API<br/>(Go + Gin)"]
    end
    
    subgraph Data["Data Layer"]
        Postgres["PostgreSQL<br/>Database"]
        Redis["Redis<br/>Cache"]
    end
    
    Browser --> SSL
    Mobile --> SSL
    SSL --> Routing
    Routing --> Frontend
    Routing --> Backend
    Frontend --> Backend
    Backend --> Postgres
    Backend --> Redis

Components Overview

1. Client Layer:

• Web Browser (Chrome, Firefox, Edge, Safari)
• Mobile Browser dengan PWA support
• Offline capability via Service Worker

2. Nginx Reverse Proxy:

• SSL/TLS termination
• Request routing
• Static file serving

3. Frontend (Next.js):

• React-based UI
• Server-side rendering (SSR)
• Client-side routing
• API client

4. Backend API (Go):

• RESTful API
• Business logic
• Data access layer
• Authentication & authorization

5. Data Layer:

• PostgreSQL: Primary database
• Redis: Caching & session storage

---

Technology Stack

Backend

• Language: Go 1.22
• Framework: Gin (HTTP web framework)
• ORM: GORM
• Database: PostgreSQL 14
• Cache: Redis 7
• Authentication: JWT (Access + Refresh tokens)
• Password Hashing: bcrypt
• Migration: golang-migrate

Key Libraries:

• github.com/gin-gonic/gin - HTTP framework
• gorm.io/gorm - ORM
• golang.org/x/crypto - Password hashing
• github.com/golang-jwt/jwt/v5 - JWT authentication

Frontend

• Framework: Next.js 14.1.0
• Language: TypeScript 5.3.3
• UI Library: React 18.2.0
• Styling: Tailwind CSS 3.3.6
• Component Library: Radix UI, ShadCN UI
• State Management: React Hooks
• Offline Storage: IndexedDB
• PWA: Service Worker, Web App Manifest
• Charts: Recharts
• PDF Export: jsPDF, html2canvas
• Excel Export: xlsx

Key Libraries:

• next - React framework
• react - UI library
• tailwindcss - CSS framework
• @radix-ui/* - UI components
• @zxing/browser - Barcode scanning

Infrastructure

• Containerization: Docker, Docker Compose
• Reverse Proxy: Nginx
• SSL: Self-signed certificates (auto-generated)
• CI/CD: GitLab CI/CD (private)

---

Database Schema

Core Tables

Organizations:

- id (UUID)
- name (VARCHAR)
- store_name (VARCHAR)
- store_address (TEXT)
- store_phone (VARCHAR)
- setup_completed (BOOLEAN)
- created_at, updated_at

Users:

- id (UUID)
- organization_id (UUID, FK)
- username (VARCHAR, UNIQUE)
- full_name (VARCHAR)
- pin_hash (VARCHAR)
- role (VARCHAR: cashier, supervisor, owner)
- created_at, updated_at

Products:

- id (UUID)
- organization_id (UUID, FK)
- name (VARCHAR)
- sku (VARCHAR, UNIQUE)
- barcode (VARCHAR)
- price_cents (INTEGER)
- cost_cents (INTEGER)
- status (VARCHAR: active, inactive)
- stock (INTEGER)
- low_stock_threshold (INTEGER)
- created_at, updated_at

Transactions:

- id (UUID)
- organization_id (UUID, FK)
- shift_id (UUID, FK)
- cashier_id (UUID, FK)
- gross_amount_cents (INTEGER)
- discount_cents (INTEGER)
- net_amount_cents (INTEGER)
- payment_method (VARCHAR)
- payment_status (VARCHAR)
- created_at, updated_at

Transaction Items:

- id (UUID)
- transaction_id (UUID, FK)
- product_id (UUID, FK)
- product_name (VARCHAR)
- quantity (INTEGER)
- unit_price_cents (INTEGER)
- discount_cents (INTEGER)
- subtotal_cents (INTEGER)
- created_at

Relationships

Organizations (1) ──< Users (N)
Organizations (1) ──< Products (N)
Organizations (1) ──< Transactions (N)
Organizations (1) ──< Shifts (N)
Transactions (1) ──< Transaction Items (N)
Products (1) ──< Transaction Items (N)
Users (1) ──< Transactions (N) [as cashier]

Indexes

Semua tabel memiliki index pada:

• organization_id (untuk multi-tenancy filtering)
• created_at (untuk sorting)
• Foreign keys

---

API Overview

Authentication Flow

sequenceDiagram
    participant Client
    participant Frontend
    participant Backend
    participant DB
    
    Client->>Frontend: Login (username, PIN)
    Frontend->>Backend: POST /api/auth/login
    Backend->>DB: Verify user & PIN
    DB-->>Backend: User data
    Backend->>Backend: Generate JWT tokens
    Backend-->>Frontend: Access + Refresh tokens
    Frontend-->>Client: Store tokens

Main Endpoints

Authentication:

• POST /api/auth/login - Login dengan username + PIN
• POST /api/auth/refresh - Refresh access token

Products:

• GET /api/products - List produk (search, pagination)
• POST /api/products - Create produk
• GET /api/products/:id - Get produk detail
• PUT /api/products/:id - Update produk
• DELETE /api/products/:id - Delete produk

Transactions:

• POST /api/checkout - Checkout transaksi
• GET /api/transactions - List transaksi
• GET /api/transactions/:id - Get transaksi detail

Inventory:

• GET /api/inventory/adjustments - List adjustments
• POST /api/inventory/adjustments - Create adjustment

Reports:

• GET /api/reports/dashboard - Dashboard data
• GET /api/reports/sales - Sales reports

Request/Response Format

Request:

• Method: GET, POST, PUT, DELETE
• Headers: Authorization: Bearer <token>
• Body: JSON (untuk POST/PUT)

Response:

• Status: 200, 201, 400, 401, 403, 404, 500
• Body: JSON
• Format: { "data": {...}, "message": "...", "error": "..." }

---

Deployment Models

Self-Hosted (Current)

Architecture:

• Single organization per instance
• Local database (PostgreSQL)
• Docker Compose deployment
• User-managed infrastructure

Characteristics:

• Data privacy (data tetap di server user)
• Full control
• No cloud dependency
• User responsible untuk backup & maintenance

Cloud-Hosted (Future)

Architecture:

• Multi-tenant
• Shared database dengan organization isolation
• Managed infrastructure
• Subscription-based

Characteristics:

• Managed backups
• Auto-scaling
• High availability
• Less control over infrastructure

Managed Services (Future)

Architecture:

• Multi-tenant dengan dedicated resources
• Managed by provider
• SLA guarantees
• Support included

Characteristics:

• Full management by provider
• SLA & support
• Higher cost
• Enterprise features

---

Security Architecture

Authentication & Authorization

JWT Token Structure:

{
  "user_id": "uuid",
  "organization_id": "uuid",
  "role": "cashier|supervisor|owner",
  "exp": 1234567890
}

Token Types:

• Access Token: Short-lived (15 minutes), digunakan untuk API calls
• Refresh Token: Long-lived (7 days), digunakan untuk refresh access token

Password Security:

• PIN di-hash menggunakan bcrypt
• Stored di users.pin_hash
• Salt rounds: 10

Data Security

Multi-Tenancy:

• Organization-based isolation
• All queries filtered by organization_id
• No cross-organization data access

Data Encryption:

• Data at rest: Database encryption (PostgreSQL)
• Data in transit: HTTPS/TLS
• Sensitive fields: Hashed (passwords)

Security Best Practices

• Input validation
• SQL injection prevention (GORM parameterized queries)
• XSS protection
• CORS configuration
• Rate limiting
• Security headers (CSP, XSS protection, etc.)

---

Offline Mode Architecture

Storage

IndexedDB Stores:

• pending_transactions - Transaksi offline yang belum sync
• cached_products - Product catalog untuk offline access
• sync_metadata - Metadata sync status

Sync Mechanism

sequenceDiagram
    participant Client
    participant ServiceWorker
    participant IndexedDB
    participant Backend
    
    Client->>IndexedDB: Save transaction (offline)
    Client->>ServiceWorker: Register background sync
    ServiceWorker->>Backend: POST /api/checkout (retry)
    Backend-->>ServiceWorker: Success
    ServiceWorker->>IndexedDB: Remove from pending

Sync Strategy:

• Background sync via Service Worker
• Exponential backoff retry (max 5 kali)
• Conflict handling (409 errors)
• Automatic sync saat online kembali

---

Performance Considerations

Backend

• Connection pooling untuk database
• Query optimization dengan indexes
• Caching untuk frequently accessed data
• Rate limiting untuk API protection

Frontend

• Code splitting untuk smaller bundles
• Image optimization
• Lazy loading untuk routes
• Caching strategies

Database

• Indexes pada frequently queried columns
• Query optimization
• Connection pooling
• Regular VACUUM dan ANALYZE

---

Scalability

Current Limitations

• Single instance deployment
• Single database per instance
• No horizontal scaling

Future Scalability

• Multi-instance deployment
• Database replication
• Load balancing
• Caching layer (Redis cluster)

---

Note: Dokumentasi ini memberikan overview moderate detail. Untuk detail implementation yang lebih dalam, lihat source code (private repository).

This site is open source. Improve this page.