Architecture

This page describes the system architecture of the Siyahfy platform, including how requests flow through the system, how the backend is organized, and how key subsystems like authentication and file storage work.

System Design

The platform follows a client-server architecture with multiple Next.js frontend applications communicating with a single Express.js backend API. A separate proxy server handles storefront routing for customer-facing stores.

Frontend Apps

All frontend apps communicate with the backend via REST API calls with JWT authentication.

Backend & Infrastructure

Storefront Proxy

Customer-facing stores go through the proxy layer:

External Services

Request Flow

Every API request passes through several layers before reaching the route handler. Here is the typical flow for an authenticated request:

Backend Route Organization

The backend organizes routes by domain. All routes are mounted under the /api prefix in index.js. Here is a summary of the major route domains:

Authentication Middleware

The backend uses four authentication middleware functions, each designed for a different user type:

How authenticate Works

The primary authenticate middleware (lib/index.js) follows this logic:

1. Check the Authorization header for a Bearer token
2. If no header token, parse cookies and check tokenSagartech, then tokenVendorsSagartech, then token
3. Strip surrounding quotes and redundant “Bearer ” prefixes
4. Validate the token matches JWT format (three dot-separated base64 segments)
5. Verify the token signature using jwt.verify(token, process.env.SECRET_KEY)
6. Check token expiration
7. Attach req.userId and req.role_id from the decoded payload
8. Call next() to pass control to the route handler

How authorizeVendor Works

The authorizeVendor middleware (middleware/index.js) is used for storefront API calls:

1. Extract Bearer token from Authorization header
2. If the token is longer than 20 characters, treat it as a JWT and verify it to extract the api_key claim
3. If the token is 20 characters or fewer, treat it directly as an API key
4. Query the stores table to find a store whose api_key JSONB array contains a matching apiKey value
5. Attach req.apiKey, req.store_name (slug), req.og_store_name, and req.vendor_id

Data Flow Example: Customer Places an Order

This sequence shows the complete flow when a customer places an order through a vendor’s storefront:

File Storage Architecture

The platform uses two cloud storage providers for different purposes:

Backblaze B2

• Primary use: Product images, category images, brand logos
• Integration: AWS S3-compatible SDK (@aws-sdk/client-s3)
• Upload flow: Multer receives files on the backend, Sharp processes/resizes images, then the S3 SDK uploads to Backblaze B2
• URL pattern: https://<bucket>.s3.<region>.backblazeb2.com/<folder>/<filename>
• Folders: Organized by type (e.g., products/, categories/, brands/)

Cloudflare R2

• Primary use: General file storage, exports, documents
• Integration: AWS S3-compatible SDK with Cloudflare endpoint
• URL pattern: https://<public-url>.r2.dev/<filename>
• Bucket: Single bucket (siyahfy-files) with path-based organization

Upload Flow

Storefront Proxy Architecture

The backend-store.siyahfy.com service is a reverse proxy that routes incoming storefront requests to the correct Next.js theme server based on the store’s domain or subdomain.

Resolution Flow

1. A customer visits myshop.site.siyahfy.com or custom-domain.com
2. The proxy extracts the hostname and determines the store slug
3. It queries PostgreSQL for the store’s theme server URL based on the vendor’s subscription plan
4. The request is proxied to the correct theme server
5. Theme resolution results are cached in memory for 60 seconds

Domain Types

Custom Domain Flow

When a vendor connects a custom domain:

1. Vendor adds the domain in the dashboard
2. Domain record is created in store_domains table with verified=false
3. Vendor configures DNS A record to point to the server IP
4. Domain verification is completed and verified is set to true
5. Traefik automatically issues a Let’s Encrypt SSL certificate on first HTTPS request
6. All subsequent requests are routed through the proxy to the store’s theme server

Database Architecture

PostgreSQL is the sole relational database. Key architectural decisions:

• Multi-tenant by convention: All stores share the same database. Tables use store_name / store_slug / vendor_id columns to scope data to a specific store.
• Auto-migrations: The backend runs pending SQL migrations from backend.siyahfy.com/migrations/ on every startup. A _migrations table tracks which files have been executed.
• JSONB usage: Several columns use PostgreSQL JSONB for flexible schema (e.g., api_key in stores, product attributes, theme configuration).
• No ORM: All queries are raw SQL via the pg driver. The connection pool is configured in config/index.js.

Caching Strategy

Redis is used as an optional caching layer:

• Connection: Configured in config/redis.js, connects to redis://127.0.0.1:6379 in development and redis://redis:6379 in production
• Graceful degradation: The backend starts and functions without Redis. Cache misses simply hit the database directly.
• Storefront proxy: The backend-store.siyahfy.com proxy uses in-memory caching (60-second TTL) for theme server resolution, independent of Redis.