DOCSEARCHbyAlgolia
Submit Docs

OpenJS Architect Framework

repository·main·Indexed 43 days ago

https://github.com/architect/arc.codes

Documentation for the OpenJS Architect framework, including guides on AWS configuration, managed runtimes (Node.js, Python, Ruby, Go, .NET, Java), custom domain setup via CloudFront and ACM, and the arc.codes documentation site structure.

Tokens
87.9K
Snippets
298
Records
431
Agent score
56%

What's inside Architect

  1. Overview of Architect core repositories and modules

    main

    The Architect ecosystem is distributed across several specialized repositories. The primary project issue tracker is located in @architect/architect.

    Core Modules

    • @architect/create: Scaffolds and generates project code.
    • @architect/deploy: Deploys an Architect project.
    • @architect/destroy: Destroys an Architect app and its resources.
    • @architect/env: Reads and writes project environment variables.
    • @architect/hydrate: Ensures Lambda dependencies are installed for AWS environments.
    • @architect/inventory: Enumerates projects into an internal intermediary format.
    • @architect/logs: Reads and writes Lambda logs.
    • @architect/package: Converts an Inventory object into a CloudFormation document.
    • @architect/parser: Lexer/parser for manifest formats (app.arc, .arc, arc.json, arc.yaml, arc.yml).
    • @architect/sandbox: Local development environment mocking AWS services (API Gateway, SNS, SQS, DynamoDB, Lambda, etc.).
    • @architect/utils: Shared internal utilities.

    Runtime Helper Libraries (Recommended)

    While not required, these make working with AWS easier:

    • @architect/functions: Node.js Lambda helpers.
    • architect/functions-python: Python Lambda helpers.
    • architect/functions-ruby: Ruby Lambda helpers.

  2. Overview of @architect/functions interfaces

    main

    The @architect/functions library provides several interfaces to interact with Architect resources:

    • arc.events: Publish/subscribe helpers for @events functions.
    • arc.http: Middleware, request/response normalization, and session support for @http functions.
    • arc.queues: Publish/subscribe helpers for @queues functions.
    • arc.services(): Retrieves the Architect service map, exposing metadata for all services in the application.
    • arc.static(): Gets a @static asset path.
    • arc.tables(): Generates a DynamoDB client for @tables.
    • arc.ws: WebSocket helpers for @ws functions.

  3. Overview of background task primitives

    main

    Architect provides three main primitives for performing asynchronous, distributed background work. These allow Lambda functions to communicate reliably while remaining stateless:

    • @events: A pub/sub message bus powered by AWS SNS. Ideal for one-to-many patterns where a single event can trigger multiple subscribed functions.
    • @scheduled: CRON-based functions invoked at specific intervals using AWS CloudWatch Events. Best for cleanup tasks, health checks, or periodic maintenance.
    • @queues: A distributed message queue powered by AWS SQS for reliable task processing.

  4. What are `hydrate` lifecycle hook plugins?

    main
    hydrate lifecycle hook plugins allow you to extend the capabilities of Hydrate (Architect's tool for managing dependencies and shared code). They provide a way to run custom logic during the dependency management lifecycle, such as copying files or performing filesystem mutations after all dependency installations and shared file operations are complete.

  5. Understand generated handler directory names for parameterized routes

    main

    When running arc create, the project generates handler directories based on your @http routes.

    Parameter Substitution Rule: For routes containing URL parameters (e.g., /pages/:dateID), the colon (:) is substituted with 000 in the generated directory name to ensure valid directory naming.

    Example Mapping:

    • Route /pages/:dateID $\rightarrow$ Directory src/http/get-pages-000dateID/
    • Route /widgets/* $\rightarrow$ Directory src/http/get-widgets-catchall/

  6. Architect Plugin Interface Overview

    main

    An Architect plugin is a module that exports an object containing specific hook functions. These functions allow plugin authors to extend Architect's core capabilities, such as modifying CloudFormation templates, defining new Lambda functions, providing runtime variables, and managing local development services in the sandbox.

    /**
 * Starter plugin template
 */

module.exports = {
  package: function ({ arc, cloudformation, stage='staging', inventory, createFunction }) {},
  functions: function ({ arc, inventory }) {}, // also aliased to `pluginFunctions`
  variables: function ({ arc, stage, inventory }) {},
  sandbox: {
    start: function ({ arc, inventory, invokeFunction, services }) {},
    end: function ({ arc, inventory, services }) {}
  }
}

  7. Understand Architect's security and IAM model

    main
    Architect apps are compiled into AWS SAM applications. By default, all resources defined in your manifest share a single IAM Role that is configured with least-privilege access, restricted only to the resources defined within that specific stack. For advanced security requirements, you can modify the generated CloudFormation to further restrict access or to allow the application to interact with AWS resources outside the scope of the current stack.

  8. Understand the Table of Contents and Sidebar structure

    main

    The site's navigation is composed of two parts:

    1. Sidebar: Dynamically generated from table-of-contents.js and the current state of the repository.
    2. Table of Contents (TOC): A collection of objects containing arrays of strings that map to Markdown documents.

    Note on nesting: The fourth level of items in the TOC will be automatically grouped into a collapsible group that is closed by default. It is recommended to use deep nesting sparingly.

  9. Manage dependencies for shared code

    main

    Resources located in @shared or @views directories can have their own dependencies. Architect will respect and copy these dependencies to the corresponding Lambdas.

    • Node.js: Define dependencies in a package.json within the shared directory.
    • Python: Define dependencies in a requirements.txt within the shared directory.
    • Ruby: Define dependencies in a Gemfile within the shared directory.

  10. Understand the difference between Userland and Pluginland Lambdas

    main

    When designing set plugins, you must decide where the Lambda handler code resides. This determines whether the consumer of your plugin manages the logic or if the plugin manages it.

    Userland Lambdas

    In this model, the plugin defines the resource (e.g., an S3 event trigger), but the actual logic (the handler) is provided by the user in their own project. This is often achieved by reading custom pragmas from the arc manifest.

    • Use case: A plugin that attaches triggers to resources where the user needs to provide the specific business logic.
    • Implementation: Use set.customLambdas to return handler paths that point to files within the user's project directory.

    Pluginland Lambdas

    In this model, the plugin provides both the resource and the handler. The handler code lives inside the plugin's own package (e.g., inside node_modules).

    • Use case: A plugin that provides a fully managed service or utility (like an automatic bundler) that the user simply enables.
    • Implementation: Use set.http, set.events, etc., and set the src property to a path relative to the plugin's directory using __dirname.
    // Example of a Pluginland Lambda (handler lives inside the plugin)
module.exports = {
  set: {
    http ({ arc, inventory }) {
      return {
        method: 'get',
        path: 'get /_bundle/:entry',
        src: __dirname + '/handler'
      }
    }
  }
}

  11. Understand the Architect project structure

    main

    By default, Architect projects follow a specific folder structure to organize code by its execution context (Lambda function type). While all folders are optional and paths can be reconfigured, the standard layout is:

    • public/: Static assets (js, css, svg, images, etc.)
    • src/shared/: Code shared by all Lambda functions
    • src/views/: Code shared by HTTP GET Lambda functions
    • src/plugins/: Custom logic to modify Architect behavior or generated CloudFormation
    • src/http/: @http Lambda functions
    • src/events/: @event Lambda functions
    • src/queues/: @queue Lambda functions
    • src/scheduled/: @scheduled Lambda functions
    • src/tables/: @table stream Lambda functions
    • src/ws/: @ws Lambda functions
    • app.arc: The project manifest file
    .
├── public
├── src
│   ├── shared
│   ├── views
│   ├── plugins
│   ├── http
│   ├── events
│   ├── queues
│   ├── scheduled
│   ├── tables
│   └── ws
└── app.arc

  12. Use @queues for asynchronous message processing

    main

    The @queues resource provisions an AWS SQS queue and registers a Lambda function to handle messages. Unlike @events (which push messages to all subscribers), @queues uses a polling mechanism where the consumer processes messages one by one. Queues provide built-in retry logic that persists for up to 4 days until a message is successfully delivered.

    To implement a queue:

    1. Define the queue in your app.arc manifest.
    2. Scaffold the function using arc init.
    3. Implement the handler in src/queues/<function-name>/index.js.
    4. Use @architect/functions to publish messages to the queue from other functions.
    # app.arc

@app
arc-queues-app

@http
get /

@queues
account-signup