These are some of the key tools and technologies used to build and develop this project:
These are some of the key dependencies required to run the applications:
@shellicar/reference-enterprise is a software architecture starter repository that provides a structured foundation for building Azure application workloads. This repository demonstrates enterprise-grade project organization with clear separation between customer-facing APIs, internal integrations, worker processes, and multiple web applications.
Unlike the foundational @shellicar/reference-foundation which illustrates individual concepts, this enterprise reference provides a complete project structure that can be used as the basis for creating new Azure application workloads.
- Overview
- @shellicar Ecosystem
- Repository Structure
- Applications
- Packages
- Infrastructure & Deployment
- Development Tools
- Getting Started
@shellicar/core-config- A library for securely handling sensitive configuration values like connection strings, URLs, and secrets.@shellicar/core-di- A basic dependency injection library.
@shellicar/reference-foundation- A comprehensive starter repository. Illustrates individual concepts.@shellicar/reference-enterprise- A comprehensive starter repository. Can be used as the basis for creating a new Azure application workload.
@shellicar/build-clean- Build plugin that automatically cleans unused files from output directories.@shellicar/build-version- Build plugin that calculates and exposes version information through a virtual module import.@shellicar/build-graphql- Build plugin that loads GraphQL files and makes them available through a virtual module import.
@shellicar/svelte-adapter-azure-functions- A SvelteKit adapter that builds your app into an Azure Function.@shellicar/cosmos-query-builder- Helper class for type safe advanced queries for Cosmos DB (Sql Core).@shellicar/ui-shadcn- Shared Svelte 5 component library built on shadcn-svelte with Tailwind CSS v4 theming.
@shellicar/winston-azure-application-insights- An Azure Application Insights transport for Winston logging library.@shellicar/pino-applicationinsights-transport- Azure Application Insights transport for pino
@shellicar/reference-enterprise provides a structured foundation for building Azure application workloads with clear architectural boundaries and separation of concerns.
This repository follows a structured approach to organising enterprise applications:
├── apps/
│ ├── api/ # Function App - User-facing APIs
│ ├── integration/ # Function App - Internal/non-user APIs
│ ├── worker/ # App Service - TemporalIO & long-running processes
│ ├── webapp/ # Main web application for users
│ ├── dashboard/ # Internal staff/line of business dashboard
│ └── admin/ # Administration interface for mature apps
├── packages/
│ ├── common/ # Code shared across frontend and backend
│ ├── server-common/ # Common functionality for Function Apps/worker
│ ├── ui/ # Framework-dependent components (Nuxt) and configuration
│ ├── ui-common/ # Framework-agnostic UI code, validation, schemas
│ ├── ui-schema/ # Schema for frontend applications
│ ├── ui-schema-admin/ # Schema for admin interface (optional)
│ ├── server-schema/ # Schema for APIs
│ ├── server-schema-api/ # Schema specifically for API (optional)
│ ├── server-schema-integration/ # Schema for integration services (optional)
│ └── typescript-config/ # Shared TypeScript configuration
├── infra/ # Infrastructure as Code (Bicep)
└── deploy/
└── templates/ # Reusable Azure Pipeline templates
| Application | Type | Purpose | Technology |
|---|---|---|---|
apps/api |
Azure Function App | User-facing APIs | Azure Functions with HTTP triggers |
apps/integration |
Azure Function App | Internal/non-user APIs | Azure Functions for third-party integrations |
apps/worker |
Azure App Service | Long-running processes | TemporalIO for workflow orchestration |
apps/webapp |
Web Application | Main user interface | Vue+Nuxt |
apps/dashboard |
Web Application | Internal staff dashboard | Vue+Nuxt |
apps/admin |
Web Application | Administration interface | Vue+Nuxt |
| Package | Purpose | What Goes Here | Used By |
|---|---|---|---|
common |
Shared code across frontend and backend | Utilities, types, constants that work everywhere | All apps |
server-common |
Server-side shared functionality | Middleware, auth helpers, server utilities | api, integration, worker |
ui |
Framework-dependent UI components | Nuxt components, framework-specific code | webapp, dashboard, admin |
ui-common |
Framework-agnostic UI code | Validation logic, Zod schemas, reusable functions | webapp, dashboard, admin |
schema-server |
Generated types for server APIs | GraphQL codegen types for server-side API consumption | Server applications |
schema-ui |
Generated types for frontend APIs | GraphQL codegen types for client-side API consumption | Frontend applications |
schema-api |
Generated types for API service (optional) | GraphQL codegen types specific to API service | api |
schema-integration |
Generated types for integration APIs (optional) | GraphQL codegen types for third-party/integration APIs | integration |
schema-admin |
Generated types for admin APIs (optional) | GraphQL codegen types specific to admin interface | admin |
typescript-config |
Shared TypeScript configuration | TSConfig files, build settings | All applications and packages |
Work in Progress - This section is under development
- Technology: Bicep templates
- Purpose: Azure resource definitions
- Contents: Resource groups, Function Apps, App Services, databases, networking
- Purpose: Reusable Azure Pipeline templates
- Contents: Build, test, and deployment pipeline definitions
- Benefits: Consistent deployment patterns across applications
Work in Progress - This section is under development
This repository includes several development tools to maintain code quality and consistency:
- Biome: Linting and formatting
- Lefthook: Git hooks for pre-commit checks
- GitVersion: Semantic versioning based on Git history
- Turbo: Monorepo task orchestration
- pnpm Workspaces: Package management and dependency resolution
- Git
- Basic understanding of Azure services
- Azure subscription (for deployment)
Run the setup script to automatically install all required tools and dependencies:
Linux/macOS:
./setup.shWindows:
.\setup.ps1The setup script will:
- Install prerequisites (Homebrew on macOS)
- Install Node Version Manager (NVM)
- Install Node.js version from
.nvmrc - Enable Corepack for package manager management
- Install pnpm via Corepack
- Install Azure Functions Core Tools
- Install Docker (optional)
If you prefer manual installation:
-
Install Node.js (version specified in
.nvmrc) -
Enable Corepack and install pnpm
corepack enable corepack prepare pnpm@latest --activate -
Install Azure Functions Core Tools
-
Clone and setup the repository
git clone https://github.com/shellicar/reference-enterprise.git cd reference-enterprise pnpm install pnpm build
Once setup is complete, you can start developing:
# Start the API
pnpm --filter api dev
# Start the web application
pnpm --filter webapp dev
# Build all packages
pnpm build
# Run tests
pnpm testThis structure provides:
- Clear separation between user-facing and internal services
- Shared code through common packages
- Scalable architecture that can grow with application complexity
- Consistent development patterns across all applications
- Flexible deployment options for different application types
This repository follows Vertical Slice Architecture - organising code by feature rather than technical layers. Each feature contains everything it needs (API endpoints, business logic, data access, validation) in one cohesive slice.
Benefits:
- High cohesion - Feature logic stays together
- Team independence - Developers can work on different features without conflicts
- Easy to understand - Business logic is contained and traceable
- Better pull requests - Code changes are colocated, making reviews easier to follow
- Deployment flexibility - Features can be developed and tested independently
Trade-offs:
- Some code duplication - Accept duplication when it keeps features independent
- Consistency overhead - Requires discipline to maintain standards across slices
- Cross-cutting changes - Security or infrastructure updates touch multiple slices
Using document databases (Cosmos DB NoSQL, MongoDB) aligns well with vertical slices:
- Features can model data as standalone documents or nested within parent entities
- Less coupling through shared database schemas
- Natural fit for feature-based data modelling
This architecture works best with teams that:
- Communicate effectively and coordinate when needed
- Recognize when duplication becomes problematic and refactor accordingly
- Balance feature independence with shared concerns
- Understand that no architecture is perfect - there are always trade-offs
This enterprise reference provides a solid foundation for Azure application workloads with clear architectural boundaries and room for growth as applications mature.
This README was created with the assistance of GitHub Copilot.