Release Notes — FirstMate Platform Backend Modules

Overview

This comprehensive release enhances the FirstMate platform’s backend services by strengthening secure, fine-grained API access control via JWT validation and dynamic permission enforcement, improving organizational onboarding workflows, repository management capabilities, and enriched AI agent interactions. The modules leverage robust continuation-local storage for request-scoped context, integrate with Stripe for subscription management, communicate asynchronously through Redis streams, and incorporate advanced language model-driven services for branch naming and question answering.

New Features

• Organization Initialization & Onboarding

  • Added secure onboarding endpoint that validates organization uniqueness and name criteria.
  • Automated Stripe customer and subscription creation during onboarding including trial periods.
  • Automatic creation or update of "GLOBAL_ADMIN" user role per organization.

• Repository Analysis & Management

  • Introduced /analyse-all API to queue full repository analysis commands for asynchronous processing using Redis streams.
  • Support for enabling/disabling repositories through API calls that update database state, invoke external Git Manager service, and trigger analysis workflows.
  • Endpoint to refresh repository metadata securely.

• Integration & Access Rights Management

  • Support for adding external access rights for organizations including Git and document providers.
  • Async initialization of document provider integrations via service bus message queuing.

• AI Agent Enhancements

  • Endpoint and service to generate context-aware branch names for change requests via LLMs with prompt templates and retry logic.
  • Internal commands API for executing provider-specific commands with permission checks.
  • Question-answering API that categorizes queries, performs context retrieval from project repositories, integrates subscription validation, and executes Langchain LLM flows with structured prompt engineering.

Improvements / Changes

• Security & Permissions Middleware

  • Refined grantAccessByPermissionMiddleware to handle multi-tenant JWT validation against JWKS endpoints dynamically fetched, including support for providers with special token formats.
  • Middleware propagating IAM context (user, org, provider, request IDs) using continuation-local storage for consistent downstream access.
  • Enhanced role-based permission checks with wildcard ("ALL") support and FirstMate-specific logic for platform-level authorization.

• Context Propagation and Logging

  • Use of cls-hooked CLS namespace to maintain request lifecycle contexts for user identity and organization data.
  • Structured logging with pino enriched with context identifiers (orgId, userId, requestId, project, service), including serialization of Axios errors and detailed stack information.

• Database Access Patterns & Models

  • Consistent MongoDB repository patterns across users, organizations, providers, and actions.
  • MongoDB queries enforce string-converted keys and scoped to organization IDs for multi-tenancy.
  • Use of repositories enables clean data access abstraction.

• Async Messaging & Event Queues

  • Asynchronous queuing of repository analysis and document provider initialization commands to Redis Streams per organization and channel.
  • Metadata-rich event messages supporting audit and routing in distributed architecture.

• Error Handling

  • Centralized application error classes with domain-specific codes.
  • Middleware and service layers propagate errors with contextual logging.

Bug Fixes

• Not explicitly indicated from the input, but midst improved error handling and permission validation, prior access control inconsistencies were addressed.

Technical / Developer Notes

• JWT verification replaced with Promise-wrapped asynchronous calls integrating with JWKS to support key rotation.
• Detailed parsing of JWT sub claim for multi-part provider identifiers (e.g., Auth0).
• Use of regular expressions to support wildcard patterns in repository filtering for enable/disable operations.
• Prompt templates for LLM interactions loaded dynamically from markdown files with ES module import.meta.url.
• Support for CLS throughout asynchronous Node.js Express routes ensures per-request security and identity context is maintained.
• Redis Streams are used as service bus channels offering reliable, append-only command/event queuing.
• Middleware parameters allow flexible dynamic specification of required permissions simplifying route-level security.
• Separation of concerns maintained through layered architecture: middleware → controller → service → repository/client for external systems.

Breaking Changes

• None reported; authentication and permission checking are enhanced but retain backward compatible JWT and role usage.
• External API endpoints remain consistent though internal middleware may enforce stricter validation rules.

Acknowledgements / Contributors

• Thanks to all backend development contributors enhancing multi-tenant security, async processing patterns, and AI integration flows.

This release significantly strengthens FirstMate’s backend infrastructure, enabling secure, extensible, and observable service operations. It integrates modern Node.js best practices, secure token validation via JWKS, subscription-billing tied onboarding, and advanced AI-powered developer workflows, setting a solid foundation for scalable multi-tenant SaaS platform evolution.