System Architecture

GSign platform architecture overview.

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         CLIENTS                                  │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐            │
│  │ Web App │  │ Mobile  │  │   API   │  │ Webhook │            │
│  │(Next.js)│  │  (PWA)  │  │ Clients │  │Consumers│            │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘            │
└───────┼────────────┼────────────┼────────────┼──────────────────┘
        │            │            │            │
        └────────────┴─────┬──────┴────────────┘
                           │
                    ┌──────▼──────┐
                    │    NGINX    │
                    │ (Load Bal.) │
                    └──────┬──────┘
                           │
┌──────────────────────────┼──────────────────────────────────────┐
│                   ┌──────▼──────┐                               │
│                   │ API Gateway │                               │
│                   │ (Go/Fiber)  │                               │
│                   └──────┬──────┘                               │
│                          │                                      │
│   ┌──────────────────────┼──────────────────────┐              │
│   │                      │                      │              │
│   ▼                      ▼                      ▼              │
│ ┌──────────┐   ┌──────────────┐   ┌──────────────┐            │
│ │ Document │   │  Signature   │   │    User      │            │
│ │ Service  │   │   Service    │   │   Service    │            │
│ └─────┬────┘   └──────┬───────┘   └──────┬───────┘            │
│       │               │                  │                     │
│       └───────────────┼──────────────────┘                     │
│                       │                                        │
│   ┌───────────────────┼────────────────────┐                   │
│   │                   │                    │                   │
│   ▼                   ▼                    ▼                   │
│ ┌───────────┐  ┌─────────────┐  ┌─────────────────┐           │
│ │Notification│ │   Billing   │  │   HSM Backend   │           │
│ │  Service  │  │   Service   │  │ (Internal Only) │           │
│ └───────────┘  └─────────────┘  └─────────────────┘           │
│                                                                 │
│                    BACKEND SERVICES                             │
└─────────────────────────────────────────────────────────────────┘
                           │
┌──────────────────────────┼──────────────────────────────────────┐
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌───────┐ │
│  │ PostgreSQL  │  │   MongoDB   │  │    Redis    │  │  S3   │ │
│  │  (Primary)  │  │  (Audit)    │  │  (Cache)    │  │(Files)│ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └───────┘ │
│                                                                 │
│                       DATA LAYER                                │
└─────────────────────────────────────────────────────────────────┘

Service Responsibilities

API Gateway (Go/Fiber)

• Rate limiting
• Authentication/Authorization
• Request routing
• API versioning
• Request/Response logging

Document Service

• File upload/download
• PDF conversion
• Document versioning
• Metadata management
• S3 integration

Signature Service

• Signing workflow engine
• Field placement
• Signature capture
• HSM integration
• Certificate operations

User Service

• User management
• Organization management
• Team management
• Role-based access control
• SSO integration

Notification Service

• Email notifications
• SMS notifications
• Webhook delivery
• In-app notifications

Billing Service

• Subscription management
• Usage tracking
• Invoice generation
• Stripe integration

HSM Backend (Internal)

• Certificate generation
• Document signing (PKCS#7)
• Certificate validation
• Key management

Data Flow

Document Signing Flow

1. User uploads document
   └── Document Service → S3

2. User creates envelope
   └── Signature Service → PostgreSQL

3. User adds recipients & fields
   └── Signature Service → PostgreSQL

4. Envelope sent
   └── Notification Service → Email

5. Recipient signs
   └── Signature Service → HSM Backend → PDF signed

6. All signed → Complete
   └── Notification Service → All parties

Database Schema

PostgreSQL (Primary)

users
├── id (UUID)
├── email
├── password_hash
├── organization_id
└── created_at

organizations
├── id (UUID)
├── name
├── plan_id
└── settings (JSONB)

documents
├── id (UUID)
├── user_id
├── name
├── s3_key
├── status
└── metadata (JSONB)

envelopes
├── id (UUID)
├── document_id
├── status
├── expires_at
└── completed_at

recipients
├── id (UUID)
├── envelope_id
├── email
├── role
├── status
└── signed_at

certificates
├── id (UUID)
├── user_id
├── label
├── type
├── status
├── valid_from
└── valid_to

MongoDB (Audit/Documents)

audit_events
├── _id
├── user_id
├── action
├── resource_type
├── resource_id
├── ip_address
├── user_agent
└── timestamp

webhook_deliveries
├── _id
├── webhook_id
├── event_type
├── payload
├── status
├── attempts
└── last_attempt

Redis (Cache/Sessions)

session:{user_id}    → User session data
cache:user:{id}      → User cache
cache:doc:{id}       → Document cache
queue:email          → Email queue
queue:webhook        → Webhook queue
rate:{ip}            → Rate limit counter

Security Architecture

Authentication Layers

1. API Gateway

   • JWT validation
   • API key validation
   • Rate limiting

2. Service Layer

   • Authorization checks (RBAC)
   • Resource ownership verification
   • Audit logging

3. Data Layer

   • Tenant isolation (tenant_id)
   • Encrypted sensitive fields
   • Connection pooling

Encryption

Data Type	Encryption
Passwords	bcrypt (cost 12)
JWT Tokens	HS256/RS256
Documents	AES-256 (at rest)
API Keys	SHA-256 hash
Certificates	PKCS#12 with password

Deployment Architecture

┌────────────────────────────────────────┐
│              AWS EC2 (t3.large)        │
│  ┌──────────────────────────────────┐  │
│  │         Docker Network           │  │
│  │                                  │  │
│  │  ┌─────────┐  ┌─────────┐       │  │
│  │  │ Backend │  │Frontend │       │  │
│  │  │ :3000   │  │ :3002   │       │  │
│  │  └────┬────┘  └────┬────┘       │  │
│  │       │            │            │  │
│  │  ┌────▼────────────▼────┐       │  │
│  │  │       NGINX          │       │  │
│  │  │    (Reverse Proxy)   │       │  │
│  │  └──────────┬───────────┘       │  │
│  │             │                   │  │
│  │  ┌──────────▼───────────┐       │  │
│  │  │   SSL (Let's Encrypt)│       │  │
│  │  └──────────────────────┘       │  │
│  │                                  │  │
│  │  Databases: PostgreSQL, MongoDB, Redis  │
│  │  Monitoring: Prometheus, Grafana        │
│  │  Logging: Loki, Promtail               │
│  │  CI/CD: GitLab CE                       │
│  └──────────────────────────────────┘  │
└────────────────────────────────────────┘