Core Concepts

Introduction

SOASAP organizes feature delivery through a hierarchy of organizations, projects, environments, feature flags, API keys, and SDKs.

Understanding how these pieces relate helps teams structure applications safely across development, staging, and production. Each layer adds isolation and scope; mistakes at one layer — for example, using a production API key in a local build — have predictable consequences if you understand the model.

This page describes the control plane and runtime boundaries. It does not walk through installation; it establishes the vocabulary used throughout the rest of the documentation.

Core concepts at a glance

Organization
↓
Project
↓
Environment
↓
API Key
↓
SDK
↓
Feature Flag Evaluation

• Organization — top-level boundary for members, roles, billing, and all projects.
• Project — scope for one application or product: flag definitions and environments.
• Environment — isolated configuration namespace (Development, Staging, Production).
• API Key — identifies one environment to the sync layer; one key per environment.
• SDK — runtime client that synchronizes configuration and evaluates flags locally.
• Feature Flag Evaluation — application code reads flag values from the SDK's in-memory snapshot.

Hierarchy overview

Every resource in SOASAP nests inside the structure below. Each concept builds on the level above it.

Organization
└─ Project
   ├─ Feature Flags (keys & types)
   └─ Environments
      ├─ Development
      ├─ Staging
      └─ Production

Within each environment:

Each Environment
├─ API Key (one per environment)
└─ Flag values (per-environment configuration)

An organization owns projects. A project defines flag keys and types, and owns environments. Each environment stores its own API key and per-flag values — including whether a flag is enabled in that environment.

Application code never talks to the organization or project layers at runtime. Only the SDK — a client library in your process, not a resource stored in SOASAP — connects using an environment API key to synchronize that environment's configuration.

Organizations

An organization is the top-level boundary in SOASAP. It represents a company, business unit, or other independent entity that manages feature flags as shared infrastructure.

Organizations define:

• Ownership — one Owner user who administers the organization
• Billing — subscription plan and usage are scoped to the organization
• Members — engineers and operators invited to the organization (shown as team members in the dashboard)
• Roles — Owner, Admin, and Member; Owners and Admins manage projects, environments, and API keys
• Access control — the security perimeter for dashboard and API operations

Organizations separate independent companies or business units. Two organizations never share projects, environments, or API keys. SOASAP has no separate Team entity — collaboration happens at the organization level through members and roles.

Example organizational structure:

Acme Corp
├─ Web Store (project)
├─ Payments Service (project)
└─ Mobile App (project)

All projects belong to an organization. Members are invited to the organization — not to individual projects — and access projects within that organization according to their role.

Team members and roles

Collaboration in SOASAP is organization-scoped. The dashboard shows invited users as team members; in the data model they are organization members — there is no separate Team entity and no per-project membership.

Members are invited by email and must accept the invitation before gaining access. Each member has one of three roles:

• Owner — full control of the organization: billing, member invitations, role changes, and all administrative actions. Each organization has one Owner.
• Admin — create and manage projects, environments, feature flags, and API keys; view audit logs. Cannot change the Owner or remove the Owner role.
• Member — collaborate within the organization on projects they can access; suitable for engineers who need to view or update flags without full administrative privileges.

Role boundaries matter for operational safety. Project creation, environment changes, and API key rotation are restricted to Owners and Admins. When onboarding a team, assign the narrowest role that matches each person's responsibility.

Projects

A project represents an application, product, or service whose feature flags you manage together. Projects are the primary unit of configuration scope below the organization.

Examples:

• Web Store
• Mobile App
• Payments Service
• Customer Portal

Each project owns:

• Feature flags — flag keys and types defined once at project scope
• Environments — Development, Staging, Production by default, or custom names you specify at creation
• Per-environment configuration — each environment holds its own API key, flag values, and enabled/disabled state

Why separate projects? Flag namespaces, access policies, and operational ownership differ by product. Mixing unrelated services into one project makes it harder to reason about blast radius, environment promotion, and who may change production flags.

Recommendations:

• Create one project per deployable product or closely coupled service group
• Do not share a project across unrelated teams unless they ship the same binary
• Name projects after the application or service operators recognize in runbooks

Environments

Environments are isolated configuration namespaces within a project. SOASAP provides Development, Staging, and Production by default; you can add more if your workflow requires them.

Environment isolation means:

• Flag keys and types are defined once per project, but values and enabled state are stored per environment
• Each environment has exactly one API key — a Development key never syncs Production configuration
• SDK instances connect to exactly one environment

The same flag key can hold different values — or be enabled in one environment and disabled in another. That is intentional: you validate behavior in lower environments before changing production.

In this example, engineers exercise the new checkout flow in Development and Staging while Production remains on the existing path. Enabling the flag in Production is a deliberate dashboard action — not a side effect of testing elsewhere.

Environment separation is critical for safe releases. Without it, a flag toggle intended for a developer workstation could affect live traffic. SOASAP enforces isolation at the API key and sync layer so each runtime receives only the configuration for its environment.

Feature flags

A feature flag is a named configuration value your application reads at runtime to decide behavior. In SOASAP, flags are defined in the dashboard and distributed to SDKs through synchronization — not fetched on each evaluation.

Supported types:

• Boolean — on/off toggles (Boolean Flags)
• String — text values such as variant names or endpoint URLs (String Flags)
• Number — integers and floating-point values for limits, rates, and thresholds (Number Flags)
• JSON — structured configuration objects (JSON Flags)

A flag's key and type belong to the project. Its value and enabled state are set independently in each environment. Flags are evaluated locally by SDKs — the SDK maintains a snapshot and serves reads from memory. Changing a flag in the dashboard does not require redeploying application code.

Examples:

// Boolean — kill switch or feature gate
client.getBool("new-checkout", false)

// String — runtime configuration
client.getString("payment-provider", "stripe")

// Number — rollout percentage, limit, or rate
client.getNumber("max-upload-mb", 10)

// JSON — structured config
client.getJson("banner-config", { "title": "", "enabled": false })

Common use cases:

• Kill switches — disable a feature immediately without a redeploy
• Gradual rollouts — expose functionality incrementally after code is already in production
• Runtime configuration — tune limits, endpoints, or copy without shipping a new binary
• Environment-specific behavior — different values per environment while code stays identical

API keys

API keys identify environments to the SOASAP sync layer. Each environment stores exactly one API key, generated when the environment is created. Each SDK instance connects using that key; SOASAP Cloud streams the matching project's environment configuration.

The mapping is one-to-one:

One environment → One API key

A Production API key syncs Production flags. A Development API key syncs Development flags. Using the wrong key in a deployment is one of the most common integration mistakes — the application runs, but flag values do not match the intended environment.

Security practices:

• Keep keys private — treat API keys like credentials; store them in secret managers or environment variables
• Do not expose production keys publicly — never commit Production keys to source control or embed them in client-side bundles shipped to end users
• Rotate keys when needed — regenerate keys after leaks, offboarding, or credential rotation policies

Server-side vs client-side usage:

• Server-side SDKs (.NET, Node.js, Python, Kotlin on backend) — API keys live in server configuration. This is the appropriate place for Production keys when flag evaluation must not be tampered with by clients.
• Client-side SDKs (React, Angular, React Native) — keys are still required for sync, but any key embedded in a mobile or browser bundle is extractable. Use Development or Staging keys in local builds; for Production client apps, accept that keys are visible and scope flags to non-sensitive toggles, or evaluate sensitive flags on your backend instead.

Details: API Keys.

SDKs

SDKs are the runtime enforcement layer. The dashboard stores configuration; the SDK applies that configuration inside your application.

Every official SOASAP SDK:

• Maintains a local snapshot of flags for its environment
• Synchronizes changes over SSE in the background
• Persists the snapshot to local storage for cold starts
• Evaluates flags locally — no network call on the read path

Deployment rule:

One SDK instance → One environment → One API key

A single process may host one SDK client configured for Production. A separate deployment or build configuration uses a different API key for Staging. Do not initialize one client with multiple environment keys — create separate instances or deployments per environment.

Install guides: SDK Installation. Runtime design: Why SOASAP.

How everything connects

The following example ties every concept together.

When an operator enables new-checkout in the Production environment:

The .NET service — configured with prod-key — receives the update over SSE, updates its local snapshot, and subsequent getBool("new-checkout", false) calls return the new value without a redeploy and without a remote evaluation request.

Common mistakes

• Using a Production API key in Development — the SDK syncs Production flag values into a local or staging build. The app runs, but behavior does not match the intended environment.
• Sharing one project across unrelated services — flag namespaces, blast radius, and operational ownership become unclear. Use one project per deployable product or closely coupled service group.
• Expecting Development changes to affect Production — environments are isolated. A flag enabled in Development does not change Production until an operator updates Production explicitly.
• Treating API keys as project identifiers — keys are environment-scoped, not project-scoped. Each environment in a project has its own key.
• Creating unnecessary SDK clients for the same environment — one process should use one SDK client per environment. Multiple clients with the same key add redundant SSE connections without benefit.

Environment isolation

Isolation exists so lower environments cannot accidentally drive production behavior.

• Development changes never affect Production automatically — different API keys, different sync streams, different flag values
• Flag values must be promoted intentionally — copying a tested value from Staging to Production is a deliberate operator action in the dashboard, not a side effect of deployment
• SDK configuration enforces the boundary — the API key in your Production deployment determines which environment's snapshot the process receives

This model reduces release risk. Engineers validate flag behavior in Development and Staging with the same code that runs in Production; only the configuration layer differs. A mistake in a Development flag value does not propagate to live traffic unless someone explicitly changes Production.

Production safety

Local evaluation shifts responsibility for safe defaults to application code. The SDK returns what is in the snapshot; if a key is missing, your code must define acceptable behavior.

Prefer explicit defaults:

client.getBool("new-checkout", false)

instead of assuming the flag exists or defaulting to an unsafe value implicitly.

Handle edge cases deliberately:

• Missing flags — return the code-level default you pass to getBool, getString, etc.
• Deleted flags — after sync, the key disappears from the snapshot; defaults apply until you remove dead code paths
• Stale environments — during outages, the SDK serves the last known snapshot; document which flags tolerate staleness
• Safe fallback behavior — default to the conservative path (feature off, old flow, lower limit) unless you have a specific reason not to

Kill switches should default to false for new features. Operational flags that gate risk should fail toward the safe state defined in code, not toward implicit enablement.

Details: Default Values and Production Safety.

How the concepts relate

Organizations contain projects. All configuration and access control roll up to the organization — members, billing, and every project live under one organizational boundary.

Projects contain environments. A project defines flag keys and types once; environments hold the per-environment values that differ across Development, Staging, and Production.

Environments own API keys and flag values. Each environment has exactly one API key and its own set of flag values and enabled states.

SDKs connect to environments using API keys. The key tells SOASAP Cloud which environment configuration to stream; the SDK maintains a local snapshot synchronized over SSE.

Applications evaluate flags through SDKs. Application code never calls SOASAP on the request path — it reads from the SDK's in-memory snapshot.

Summary

The SOASAP mental model in one chain:

Organization
→ Project
→ Environment
→ API Key
→ SDK
→ Feature Flag Evaluation

Organizations scope access, members, and billing. Projects scope flag definitions and environments. Environments isolate values, enabled state, and API keys. SDKs evaluate flags locally from a synchronized snapshot.

Next steps:

• Quick Start — create a project and evaluate your first flag
• Feature Flags — types, defaults, and usage patterns
• Architecture — local evaluation, SSE, cache, and offline operation
• SDK Installation — packages and platform guides

Context: What is SOASAP and Create Your First Flag.