"Hello Alice!" - A Production-Ready scaffold in NPL

General
1

Many developers have experienced the frustration of starting a new project with a basic “Hello World” example, only to find themselves overwhelmed by the complexities of real-world applications. From managing user authentication and authorization to designing robust database schemas and implementing comprehensive audit logging, the initial excitement can quickly turn into a daunting challenge. These pain points often lead to a cycle of trial and error, where developers spend more time troubleshooting than building.

What if your “Hello World” wasn’t just an example, but a production-ready foundation? Let’s be honest: most “Hello World” examples are throwaway code. You write them, you run them once, maybe you show them in a demo. But when it’s time to build something real, you’re suddenly shaping and wiring up authentication, authorization, database schemas, audit logging, API documentation…

Why NPL Exists

NPL (NOUMENA Protocol Language) takes a different approach to backend development. Instead of starting with a bare HTTP endpoint and layering on security, persistence, and compliance features later, NPL bakes these into the language itself.

The vision is straightforward: enable developers to build backend applications more easily and go to production faster. Not by adding more abstractions or frameworks, but by making the right things automatic and the complex things explicit.

A Different Kind of Hello World

Here’s a complete NPL protocol that implements a greeting process:

package demo;

@api
protocol[greeter] HelloWorld() {
    initial state greeting;
    final state greeted;
    @api
    permission[greeter] sayHello() returns Text | greeting {
        become greeted;
        return "Hello " + getUsername(greeter) + "!";
    };
};

function getUsername(party: Party) returns Text -> 
    party.claims()
    .getOrNone("preferred_username")
    .getOrFail()
    .toList()
    .get(0);

This isn’t just a function that returns a string. It’s a complete backend service with:

  • Authorization built in: Only users matching the greeter party can call sayHello()
  • State management: The protocol transitions from greeting to greeted
  • Automatic persistence: Every instance and state change is stored in PostgreSQL
  • Full audit trail: All actions are logged automatically
  • REST API generation: OpenAPI-compliant endpoints created at deployment

How It Actually Works

When you deploy this protocol, NPL automatically generates REST endpoints. Here’s what happens in practice:

1. Create a Protocol Instance

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{"@parties": {"greeter": {"claims": {"email": ["alice@example.com"]}}}}' \
  http://localhost:12000/npl/demo/HelloWorld/

This creates a new HelloWorld instance where only users with the email “alice@example.com” can interact with it. The instance is immediately persisted to PostgreSQL with a full schema NPL manages for you.

2. Call the Permission

curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://localhost:12000/npl/demo/HelloWorld/{id}/sayHello

NPL validates the user’s JWT against the greeter party claims. If they match, the protocol:

  • Executes the permission logic
  • Transitions the state from greeting to greeted
  • Persists the new state
  • Logs the action with full audit trail
  • Returns the greeting

If something goes wrong—wrong state, failed authorization, runtime error—the entire transaction rolls back. No partial states, no manual cleanup.

What Makes This Production-Ready?

Let’s compare this to a typical Node.js or Python hello world. To make that production-ready, you’d need to add:

What You’d Normally Build:

  • JWT validation middleware
  • Role-based access control
  • Database schema and migrations
  • State machine logic
  • Transaction handling
  • Audit logging
  • API documentation
  • Error handling and rollback logic

What NPL Gives You:

  • Zero DDL: NPL manages your entire PostgreSQL schema
  • Automatic versioning: Every state change is versioned for compliance
  • Built-in authorization: Party-based access control at the language level
  • Transactional guarantees: All-or-nothing execution
  • Audit by default: Every action logged without extra code
  • OpenAPI generation: Swagger UI included

Who Is This For?

NPL shines when you need:

  • Fast prototyping with production constraints: Your MVP needs real auth and persistence
  • Multi-party workflows: Different users with different permissions
  • Compliance requirements: Audit trails, GDPR support built-in
  • Complex state management: Business processes with clear state transitions

It’s probably not the right fit if you’re building:

  • Frontend-only applications
  • Big data pipelines
  • High-frequency trading systems
  • Simple CRUD APIs without authorization needs

Getting Started Is Actually Simple

# Install NPL
brew install NoumenaDigital/tools/npl
# Create a project
npl init --project-dir my-project
# Start the runtime
cd my-project && docker compose up --wait
# Deploy your code
npl deploy

Your API is now running at http://localhost:12000/swagger-ui/. That’s it.

The Real Promise

We’re not trying to replace every backend technology. NPL is purpose-built for applications where business logic, authorization, and data persistence are tightly coupled—which, honestly, describes most backend services.

The promise is simple: write your business logic in protocols, and let NPL handle the infrastructure concerns that usually take weeks to get right. Your Hello World isn’t a toy—it’s the same pattern you’ll use in production.

Want to try it yourself? Check out the getting started guide or explore more NPL examples. The complete Hello World example is available in the npl-init repository.

NPL is developed by NOUMENA Digital. We believe backend development should focus on business logic, not boilerplate. If you’re tired of writing the same authorization, and persistence code for every project, give NPL a try.

1 Like