Platform, Architecture & Foundations

1. Architecture and Single-Binary Distribution

What SamvraCore ERP is

SamvraCore ERP is a multi-tenant ERP delivered as a single self-contained Go 1.25 binary. The React 19 + TypeScript frontend is compiled by Vite and embedded directly into that binary at build time using //go:embed dist/*, wired through frontend/embed_prod.go and frontend/serve.go. This means one artefact contains both the API server and the web UI, so there is no separate web server or static-asset host to deploy.

The codebase is organised in layers. The inventory for v1.11.82 records 34 backend usecase modules under internal/usecase/, 77 Gin HTTP controllers under internal/adapter/controller/, 73 domain entities under internal/domain/entity/, and roughly 80 repository implementations under the Postgres persistence package. On the frontend there are over 180 page components across 38 domain folders and 51 API service modules.

Runtime stack

The server uses the Gin HTTP framework. The frontend is a Vite-built single-page application styled with Tailwind CSS 4 and Lucide icons, using React Context plus custom hooks for state. The Axios client auto-injects the Bearer token and performs a refresh on a 401 response. Rich UI primitives include the TipTap rich-text editor, Recharts charts, and dnd-kit drag-and-drop.

A Redux Toolkit store is installed but currently unused; the live state model is React Context with custom hooks. The reference production deployment runs at samvracore.tech. Because the binary embeds everything it needs, a typical install is one file plus a database, which keeps the deployment surface small and predictable across operating systems.

2. The Install Wizard and First-Boot Provisioning

Six-step web wizard

On first boot the binary serves a web-based install wizard on port :8080, implemented under internal/installer/. The operator walks through six stages in order: Licence, Database, Admin, Organization, SSL/Port, Review, then Install. During the final step the installer runs the database migrations, creates the first admin user and organization, generates the JWT secret, and writes config.yaml.

Headless provisioning

For unattended or scripted installs there is a headless variant, installer.BootstrapFromEnv, activated by setting BOOTSTRAP_MODE=env (or envwizard). It reads LICENSE_KEY, the DATABASE_* variables, the ADMIN_* variables, and ORG_NAME from the environment and performs the same provisioning without operator interaction. This supports container and automated deployment pipelines.

Idempotency and recovery

A .installed marker file prevents the wizard from running again after a successful install, and the configuration write is atomic. The wizard is also tied into licence recovery. If license.CheckLocalToken fails after installation, the wizard re-launches so the operator can paste a fresh key. A background poller exits once a valid token appears, which lets the Windows SCM or systemd supervisor restart the service into the normal licensed path. A typical workflow is therefore install once, then rely on the marker to keep subsequent restarts going straight to the application.

3. Licence Activation and Machine Fingerprinting

Server-issued JWT model

From v1.5.37 onward the product uses a server-issued JWT licence model. SMVR-format licence keys are validated against the activation server at https://listener.samvracore.tech/licences/activate. Tokens are Ed25519-signed JWTs, and the public key is embedded at build time in pkg/license/server.go. Each token has a 90-day TTL, with background revalidation every 7 days against the /licences/verify endpoint.

Machine fingerprint

Activation is bound to a machine fingerprint computed per platform. On Linux it reads /etc/machine-id, on macOS the IOPlatformUUID, and on Windows the registry value at HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid. This ties a licence token to the host it was activated on.

Token resolution and safety

The token path is resolved through a defined chain. It first checks the SAMVRACORE_LICENCE_TOKEN_PATH environment variable, then ${SAMVRACORE_DATA_DIR}/licence.token, then on Windows %ProgramData%\SamvraCore ERP\licence.token, then the user config directory, and finally /var/lib/. A deliberate token-loss safety rule keeps an operator in the loop: if the token is invalid the install wizard is launched rather than a silent re-fetch being attempted. This ensures a human confirms re-activation instead of the system quietly reaching out to the licence server.

4. Cross-Platform Distribution and In-App Updates

Five platform builds

The product ships for five distribution platforms: Linux amd64, Linux arm64, macOS Apple Silicon (arm64), macOS Intel (amd64), and Windows amd64. Linux uses a systemd service and tarball installer (User=samvracore, Restart=always). macOS ships as a single binary. Windows uses an NSIS installer plus a Windows service run through the SCM dispatcher in golang.org/x/sys/windows/svc.

Windows service specifics

On Windows the installer asks the operator for a data folder, writes SAMVRACORE_DATA_DIR as a system environment variable and as a per-service Environment REG_MULTI_SZ entry so the SCM-launched service sees env vars without a reboot, and configures an sc failure auto-restart policy. Boot-trace logging across candidate paths and service-log redirection to service.log help diagnose SCM or systemd start failures.

Admin-triggered updates

Updates are driven from the admin UI (the Updates page) through three endpoints under /api/v1/admin/updates for status, check, and install. The update manifest is fetched from https://downloads.samvracore.tech/samvracore-erp/latest.json. The install path verifies a SHA-256 checksum, swaps the binary in place, flushes the response after about 1.5 seconds, calls os.Exit(0), and lets systemd or the Windows SCM respawn the new binary. Build targets include make dist and per-platform variants, and slim variants exclude the GCS and Azure SDKs to reduce binary size.

5. Database, Migrations and Multi-Tenancy

Datastore

Persistence is on PostgreSQL 16 accessed with PGX v5 direct SQL and no ORM, using connection pooling and prepared statements throughout. Redis 7 provides caching via pkg/cache/. For development and test runs an embedded Postgres is available through pkg/embedpg/.

Migrations

The schema is managed by 209 sequential SQL migrations under the migrations package, each with explicit up and down files. A custom migration tool at cmd/migrate/main.go supports run, rollback, status, and create operations. Row-Level Security policies exist on every multi-tenant table.

Tenant isolation

Multi-tenant isolation is enforced in two complementary ways. Every entity carries an organization_id column for application-layer filtering, and PostgreSQL Row-Level Security is applied as defence in depth. The current tenant is set per transaction through the app.current_tenant session variable, wired via DB.WithTenantTransaction(). A typical request therefore opens a tenant-scoped transaction, which causes RLS policies to restrict every query to the active organization even if an application-layer filter were missed. This layered approach means a bug in one layer does not by itself leak data across tenants.

6. Security Posture

Authentication and authorization

Passwords are hashed with bcrypt at cost 10 (pkg/utils/HashPassword). Authentication uses short-lived JWT access tokens plus rotating refresh tokens from pkg/jwt/. Authorization is handled by RBAC middleware (pkg/middleware/rbac.go) with a 5-minute permission cache and wildcard resource:action matching; the cache is invalidated when a role or permission changes. System roles are immutable, while custom roles allow permission selection.

Data protection

Sensitive fields are encrypted with AES-GCM via pkg/encryption/. The portal-credential vault layers that encryption with per-organization key derivation. Row-Level Security runs alongside application-layer tenant filtering so tenant isolation does not depend on a single mechanism.

Request and operational hardening

The embedded HTTP server supports TLS, configurable through the install wizard. The middleware layer includes CSRF protection, rate limiting, and an IP allowlist (pkg/middleware/), and audit logging runs on every state-changing endpoint. Recovery options include security questions for account recovery and standard password-reset flows. The install wizard itself is hardened with the .installed marker and atomic config writes. An error taxonomy in pkg/errors/AppError maps application errors to the correct HTTP status codes.

7. Internationalization, Settings and Integrations

i18n

The application ships 22 locales with 22 namespaces per locale, including auth, common, dashboard, errors, hr, sales, inventory, settings, accounting, admin, gst, payroll, support and vendor. A no-fallback policy means every locale-by-namespace combination has native content. Right-to-left support is provided via applyDir() and an <html dir="rtl"> toggle for Urdu, with bundled Indic fonts (Noto Sans Indic, Noto Nastaliq Urdu, Noto Sans Ol Chiki, Noto Sans Meetei Mayek). ICU MessageFormat is supported via i18next-icu. A CI gate, make i18n-gate, enforces a per-locale coverage floor, and translation tooling lives at cmd/i18n/ with export, import, status, audit and gate sub-commands.

Settings and configuration

The Settings page covers organization details (name, slug, website domain, logo), functional currency, language, region and timezone, date and time formats, SMTP email configuration (with examples for Amazon SES, Gmail, Outlook and SendGrid using STARTTLS or SSL), a theme picker (Light, Dark, Follow System), session timeout, maximum login attempts, notification preferences, magic-link and invitation expiration, and customer and vendor portal settings.

Integrations

Built-in integrations include the Razorpay payment gateway, Mailgun and SMTP email via pkg/email/, S3-compatible file storage with a local filesystem fallback (pkg/storage/), and PDF generation. These are the external touchpoints the ERP relies on for billing, notifications, document storage and output.