Developer Documentation

Last updated: January 2025

1. Overview

Seesam NFC is a universal NFC access control platform designed for modern buildings. Our system provides a secure, mobile-first solution that works with existing access control hardware through an adapter-based architecture.

Key Features

2. Technical Architecture

Backend Stack

Frontend Stack

Infrastructure

3. Hardware Adapter Pattern

Our adapter-based architecture allows seamless integration with different access control hardware vendors without changing core business logic.

Why Adapter Pattern?

The Hardware Adapter Pattern decouples the system from vendor-specific APIs, enabling:

Architecture Overview

Application Layer (DoorService, UserSyncService)
         │
         ▼
Hardware Provider Interface
         │
         ▼
Adapter Layer (HotSecAdapter, YourAdapter)
         │
         ▼
External Hardware APIs

Vendor-Agnostic Domain Models

All hardware interactions use standardized domain models:

Implementing Your Own Adapter

To integrate a new hardware vendor, implement these interfaces:

  1. HardwareAuthenticationProvider - Handles vendor API authentication and token management
  2. HardwareUserProvider - Manages user synchronization with hardware system
  3. HardwareDoorProvider - Controls door access operations
  4. HardwareProvider - Main facade that combines all sub-providers

Example: Basic Adapter Structure

@Service
@ConditionalOnProperty(name="hardware.adapter", havingValue="yourvendor")
public class YourVendorHardwareProvider implements HardwareProvider {

    @Override
    public HardwareAuthenticationProvider getAuthenticationProvider() {
        return new YourVendorAuthAdapter();
    }

    @Override
    public HardwareUserProvider getUserProvider() {
        return new YourVendorUserAdapter();
    }

    @Override
    public HardwareDoorProvider getDoorProvider() {
        return new YourVendorDoorAdapter();
    }
}

Configuration

Activate your adapter in application.yml:

hardware:
  adapter: yourvendor  # Options: hotsec, yourvendor
  api:
    server: https://api.yourvendor.com
    username: ${HARDWARE_API_USERNAME}
    password: ${HARDWARE_API_PASSWORD}

4. Deployment Options

Standalone Server

Run as a Java application on Windows, Linux, or macOS servers. Ideal for traditional IT infrastructure with straightforward setup and management.

Docker Container

Deploy using our multi-stage Dockerfile for consistent environments across development, staging, and production. Includes:

Kubernetes

Production-grade deployment with:

Managed Cloud (SaaS)

We host and manage everything on AWS EKS. Each customer receives:

5. Getting Started

For Developers

Clone the repository and set up your local environment:

# Prerequisites
- Docker Desktop (required for PostgreSQL)
- Node.js 18+
- Java 17+

# Start development stack
docker-compose up -d

# Run backend
cd backend
./mvnw spring-boot:run

# Run frontend
cd frontend
npm install
npm run dev

For Hardware Integrators

To integrate your access control hardware:

  1. Review the Hardware Adapter Pattern section above
  2. Implement the required provider interfaces
  3. Map your vendor API to our domain models
  4. Configure activation via @ConditionalOnProperty
  5. Write comprehensive unit tests
  6. Submit for code review and integration

For System Administrators

Deploy using your preferred method from our deployment options. All methods require:

6. Security

Authentication

Data Protection

Compliance

7. Support & Resources

Getting Help

Additional Documentation

Ready to integrate? Schedule a demo to discuss your specific requirements and get started with Seesam NFC.