Skip to content
Surkyl Docs

Monorepo Structure

Monorepo Structure

Section titled “Monorepo Structure”

The Surkyl Platform AIO (All-In-One) monorepo is organized using Nx, a powerful build system designed for monore repos. This guide explains how the codebase is structured and organized.

Directory Overview

Section titled “Directory Overview”
aio/
├── apps/              # Applications (deployable services and websites)
├── libs/              # Shared libraries and utilities
├── plugins/           # Custom Nx plugins
├── .ai/              # AI agent configuration and rules
├── .vscode/          # VS Code workspace settings
└── configs/          # Shared configuration files

Applications (apps/)

Section titled “Applications (apps/)”

Production-ready applications that can be deployed independently:

Backend Services

Section titled “Backend Services”
  • gate: High-performance API gateway (Rust + Axum)
  • surkyl-server: Main backend server with authentication and RBAC (Rust + Axum + SQLx)
  • godseye-proxy: PostHog reverse proxy for analytics (Rust)
  • nanx: Workflow execution service (Rust)

Frontend Applications

Section titled “Frontend Applications”
  • playground: Development playground and demo app (Angular 20+)
  • identity-ui: User authentication and identity management UI (Angular 20+)
  • identity-ui-e2e: E2E tests for identity-ui (Playwright)
  • playground-e2e: E2E tests for playground (Playwright)

Websites

Section titled “Websites”
  • docs: This documentation site (Astro + Starlight)
  • muesync-com: MueSync landing page and marketing site (Astro)
  • surkyl-com: Surkyl company website (Astro)

Libraries (libs/)

Section titled “Libraries (libs/)”

Reusable libraries shared across applications:

Frontend Libraries

Section titled “Frontend Libraries”
  • pixel: Modern Angular component library with Material Design
    • Theme system with TailwindCSS
    • Workflow Engine (NanX Flows): YAML-based workflow automation
    • Reusable UI components

Backend Libraries (Rust)

Section titled “Backend Libraries (Rust)”
  • surkyl_core: Core Rust utilities and shared functionality
  • hypers: HTTP utilities and middleware helpers
  • muesync: MueSync-specific utilities
  • nanions: Background job and queue management
  • visc: Validation and utility library

Plugins (plugins/)

Section titled “Plugins (plugins/)”

Custom Nx plugins extending build capabilities:

  • nx-astro: Nx plugin for Astro/Starlight projects
  • nx-sveltekit: Nx plugin for SvelteKit applications

Configuration

Section titled “Configuration”

Workspace Configuration

Section titled “Workspace Configuration”
  • nx.json: Nx workspace configuration
  • package.json: Root package dependencies and scripts
  • pnpm-workspace.yaml: pnpm workspace configuration
  • tsconfig.base.json: Base TypeScript configuration

Rust Configuration

Section titled “Rust Configuration”
  • Cargo.toml: Workspace Cargo configuration
  • Cargo.lock: Locked dependency versions

Project Configuration

Section titled “Project Configuration”

Each project has its own configuration:

  • project.json: Nx project configuration (targets, executors)
  • package.json: Project-specific dependencies (TypeScript/JavaScript)
  • Cargo.toml: Project-specific dependencies (Rust)
  • tsconfig.json: Project-specific TypeScript config

Dependency Graph

Section titled “Dependency Graph”

Visualize the project dependencies:

Terminal window
nx graph

This opens an interactive visualization showing:

  • Project dependencies
  • Library usage
  • Task execution order

Project Types

Section titled “Project Types”

Applications

Section titled “Applications”

Applications are deployable and can run independently:

  • Have their own entry points
  • Can be built and deployed
  • May depend on libraries
  • Located in apps/

Libraries

Section titled “Libraries”

Libraries are not deployable and provide shared functionality:

  • Must be imported by applications or other libraries
  • Cannot run standalone
  • Promote code reuse
  • Located in libs/

Naming Conventions

Section titled “Naming Conventions”

Directory Names

Section titled “Directory Names”
  • kebab-case: surkyl-server, identity-ui, godseye-proxy
  • Descriptive and concise
  • Separate words with hyphens

Project Names

Section titled “Project Names”

In project.json:

  • Match directory names
  • Use @ org prefix for published packages: @surkyl/pixel

File Names

Section titled “File Names”
  • TypeScript/JavaScript: kebab-case.ts, user-service.ts
  • Rust: snake_case.rs, user_service.rs
  • Components: kebab-case.component.ts
  • Tests: *.spec.ts, *_test.rs

Build Output

Section titled “Build Output”

Build artifacts are generated in:

  • dist/: TypeScript/JavaScript builds
  • dist/target/: Rust builds (via Cargo)

Technology Stack by Project Type

Section titled “Technology Stack by Project Type”

Rust Applications

Section titled “Rust Applications”
  • Framework: Axum 0.8
  • Database: SQLx with PostgreSQL
  • Testing: Cargo test
  • Build: Cargo + Nx

Angular Applications

Section titled “Angular Applications”
  • Framework: Angular 20+ (standalone components)
  • Styling: TailwindCSS + Angular Material
  • Testing: Vitest, Playwright
  • Build: esbuild via Nx

Astro Sites

Section titled “Astro Sites”
  • Framework: Astro 5+
  • UI: Starlight (docs), TailwindCSS
  • Build: Astro build via Nx

Workspace Commands

Section titled “Workspace Commands”

Running Tasks

Section titled “Running Tasks”
Terminal window
# Run a single task
nx <target> <project>


# Examples
nx serve playground
nx build gate
nx test pixel
nx e2e identity-ui-e2e

Running Multiple Tasks

Section titled “Running Multiple Tasks”
Terminal window
# Run task for all projects
nx run-many --target=build --all


# Run task for specific projects
nx run-many --target=test --projects=pixel,playground


# Run affected tasks (only changed projects)
nx affected --target=build

Viewing Information

Section titled “Viewing Information”
Terminal window
# Show project details
nx show project <project-name>


# List all projects
nx show projects


# View dependency graph
nx graph

Best Practices

Section titled “Best Practices”

Dependency Management

Section titled “Dependency Management”
  1. Shared Dependencies: Keep common versions in root package.json
  2. Project Dependencies: Only add project-specific deps to project package.json
  3. Rust Workspace: Use workspace dependencies in root Cargo.toml

Project Organization

Section titled “Project Organization”
  1. Single Responsibility: Each project should have a clear, single purpose
  2. Loose Coupling: Minimize dependencies between projects
  3. High Cohesion: Keep related code together

Code Sharing

Section titled “Code Sharing”
  1. Extract Common Code: Move shared code to libraries
  2. Avoid Circular Dependencies: Libraries should not depend on apps
  3. Version Together: All projects share the same version (monorepo benefit)

Next Steps

Section titled “Next Steps”