{"id":32558371,"url":"https://github.com/shellicar/reference-enterprise","last_synced_at":"2025-10-28T23:55:32.922Z","repository":{"id":300358758,"uuid":"1005863035","full_name":"shellicar/reference-enterprise","owner":"shellicar","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-24T09:38:58.000Z","size":1312,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-24T11:23:41.783Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shellicar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-21T01:03:16.000Z","updated_at":"2025-10-24T09:38:08.000Z","dependencies_parsed_at":"2025-08-24T01:39:11.772Z","dependency_job_id":null,"html_url":"https://github.com/shellicar/reference-enterprise","commit_stats":null,"previous_names":["shellicar/reference-enterprise"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/shellicar/reference-enterprise","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellicar%2Freference-enterprise","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellicar%2Freference-enterprise/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellicar%2Freference-enterprise/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellicar%2Freference-enterprise/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shellicar","download_url":"https://codeload.github.com/shellicar/reference-enterprise/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellicar%2Freference-enterprise/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281533443,"owners_count":26517827,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-28T02:00:06.022Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-28T23:54:31.360Z","updated_at":"2025-10-28T23:55:32.916Z","avatar_url":"https://github.com/shellicar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @shellicar/reference-enterprise\n\n[![Node.js](https://img.shields.io/badge/Node.js-22-5FA04E?logo=nodedotjs)][node]\n[![npm](https://img.shields.io/badge/npm-10-CB3837?logo=npm)][npm]\n[![pnpm](https://img.shields.io/badge/pnpm-10-F69220?logo=pnpm)][pnpm]\n[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6?logo=typescript)][typescript]\n[![nvm](https://img.shields.io/badge/nvm-0.40-F4DD4B?logo=nvm)][nvm]\n[![Docker](https://img.shields.io/badge/Docker-dev-2496ED?logo=docker)][docker]\n[![Checked with Biome](https://img.shields.io/badge/Checked_with-Biome-60A5FA?style=flat\u0026logo=biome)][biome]\n[![AI Assisted](https://img.shields.io/badge/AI--Assisted-Copilot-501DAF?logo=github)][copilot]\n[![VS Code](https://img.shields.io/badge/VS%20Code-IDE-007ACC?logo=visualstudiocode\u0026logoColor=white)][vscode]\n\n## Built Using\n\nThese are some of the key tools and technologies used to build and develop this project:\n\n[![Vite](https://img.shields.io/badge/Vite-5-646CFF?logo=vite)][vite]\n[![esbuild](https://img.shields.io/badge/esbuild-0.24-FFCF00?logo=esbuild)][esbuild]\n[![TSX](https://img.shields.io/badge/TSX-4-3178C6)][tsx]\n\n## Runs On\n\nThese are some of the key dependencies required to run the applications:\n\n[![@azure/functions](https://img.shields.io/badge/Azure%20Functions-4-0082FC?logo=github)][azure-functions]\n[![GraphQL](https://img.shields.io/badge/GraphQL-16-E10098?logo=graphql)][graphql]\n[![Nuxt.js](https://img.shields.io/badge/Nuxt-4-00DC82?logo=nuxt.js)][nuxt]\n[![Tailwind CSS](https://img.shields.io/badge/Tailwind%20CSS-4-06B6D4?logo=tailwindcss)][tailwind]\n[![Zod](https://img.shields.io/badge/Zod-4-3E67B1?logo=zod\u0026logoColor=3E67B1)][zod]\n[![js-joda](https://img.shields.io/badge/js--joda/core-5-2C3E50?logo=github)][js-joda]\n[![Winston](https://img.shields.io/badge/Winston-3-5B8C5B?logo=github)][winston]\n[![OpenTelemetry](https://img.shields.io/badge/OpenTelemetry-1-000000?logo=opentelemetry\u0026logoColor=white)][opentelemetry]\n\n---\n\n`@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.\n\nUnlike the foundational [`@shellicar/reference-foundation`](https://github.com/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.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [@shellicar Ecosystem](#shellicar-typescript-ecosystem)\n- [Repository Structure](#repository-structure)\n- [Applications](#applications)\n- [Packages](#packages)\n- [Infrastructure \u0026 Deployment](#infrastructure--deployment)\n- [Development Tools](#development-tools)\n- [Getting Started](#getting-started)\n\n\u003c!-- BEGIN_ECOSYSTEM --\u003e\n\n## @shellicar TypeScript Ecosystem\n\n### Core Libraries\n\n- [`@shellicar/core-config`](https://github.com/shellicar/core-config) - A library for securely handling sensitive configuration values like connection strings, URLs, and secrets.\n- [`@shellicar/core-di`](https://github.com/shellicar/core-di) - A basic dependency injection library.\n\n### Reference Architectures\n\n- [`@shellicar/reference-foundation`](https://github.com/shellicar/reference-foundation) - A comprehensive starter repository. Illustrates individual concepts.\n- [`@shellicar/reference-enterprise`](https://github.com/shellicar/reference-enterprise) - A comprehensive starter repository. Can be used as the basis for creating a new Azure application workload.\n\n### Build Tools\n\n- [`@shellicar/build-clean`](https://github.com/shellicar/build-clean) - Build plugin that automatically cleans unused files from output directories.\n- [`@shellicar/build-version`](https://github.com/shellicar/build-version) - Build plugin that calculates and exposes version information through a virtual module import.\n- [`@shellicar/build-graphql`](https://github.com/shellicar/build-graphql) - Build plugin that loads GraphQL files and makes them available through a virtual module import.\n\n### Framework Adapters\n\n- [`@shellicar/svelte-adapter-azure-functions`](https://github.com/shellicar/svelte-adapter-azure-functions) - A [SvelteKit adapter](https://kit.svelte.dev/docs/adapters) that builds your app into an Azure Function.\n- [`@shellicar/cosmos-query-builder`](https://github.com/shellicar/cosmos-query-builder) - Helper class for type safe advanced queries for Cosmos DB (Sql Core).\n\n### Logging \u0026 Monitoring\n\n- [`@shellicar/winston-azure-application-insights`](https://github.com/shellicar/winston-azure-application-insights) - An [Azure Application Insights](https://azure.microsoft.com/en-us/services/application-insights/) transport for [Winston](https://github.com/winstonjs/winston) logging library.\n- [`@shellicar/pino-applicationinsights-transport`](https://github.com/shellicar/pino-applicationinsights-transport) - [Azure Application Insights](https://azure.microsoft.com/en-us/services/application-insights) transport for [pino](https://github.com/pinojs/pino)\n\n\u003c!-- END_ECOSYSTEM --\u003e\n\n## Overview\n\n**@shellicar/reference-enterprise** provides a structured foundation for building Azure application workloads with clear architectural boundaries and separation of concerns.\n\n## Repository Structure\n\nThis repository follows a structured approach to organising enterprise applications:\n\n```text\n├── apps/\n│   ├── api/                    # Function App - User-facing APIs\n│   ├── integration/            # Function App - Internal/non-user APIs\n│   ├── worker/                 # App Service - TemporalIO \u0026 long-running processes\n│   ├── webapp/                 # Main web application for users\n│   ├── dashboard/              # Internal staff/line of business dashboard\n│   └── admin/                  # Administration interface for mature apps\n├── packages/\n│   ├── common/                 # Code shared across frontend and backend\n│   ├── server-common/          # Common functionality for Function Apps/worker\n│   ├── ui/                     # Framework-dependent components (Nuxt) and configuration\n│   ├── ui-common/              # Framework-agnostic UI code, validation, schemas\n│   ├── ui-schema/              # Schema for frontend applications\n│   ├── ui-schema-admin/           # Schema for admin interface (optional)\n│   ├── server-schema/          # Schema for APIs\n│   ├── server-schema-api/             # Schema specifically for API (optional)\n│   ├── server-schema-integration/     # Schema for integration services (optional)\n│   └── typescript-config/      # Shared TypeScript configuration\n├── infra/                      # Infrastructure as Code (Bicep)\n└── deploy/\n    └── templates/              # Reusable Azure Pipeline templates\n```\n\n## Applications\n\n| Application | Type | Purpose | Technology |\n|-------------|------|---------|------------|\n| `apps/api` | Azure Function App | User-facing APIs | Azure Functions with HTTP triggers |\n| `apps/integration` | Azure Function App | Internal/non-user APIs | Azure Functions for third-party integrations |\n| `apps/worker` | Azure App Service | Long-running processes | TemporalIO for workflow orchestration |\n| `apps/webapp` | Web Application | Main user interface | Vue+Nuxt |\n| `apps/dashboard` | Web Application | Internal staff dashboard | Vue+Nuxt |\n| `apps/admin` | Web Application | Administration interface | Vue+Nuxt |\n\n## Packages\n\n| Package | Purpose | What Goes Here | Used By |\n|---------|---------|----------------|---------|\n| `common` | Shared code across frontend and backend | Utilities, types, constants that work everywhere | All apps |\n| `server-common` | Server-side shared functionality | Middleware, auth helpers, server utilities | `api`, `integration`, `worker` |\n| `ui` | Framework-dependent UI components | Nuxt components, framework-specific code | `webapp`, `dashboard`, `admin` |\n| `ui-common` | Framework-agnostic UI code | Validation logic, Zod schemas, reusable functions | `webapp`, `dashboard`, `admin` |\n| `schema-server` | Generated types for server APIs | GraphQL codegen types for server-side API consumption | Server applications |\n| `schema-ui` | Generated types for frontend APIs | GraphQL codegen types for client-side API consumption | Frontend applications |\n| `schema-api` | Generated types for API service (optional) | GraphQL codegen types specific to API service | `api` |\n| `schema-integration` | Generated types for integration APIs (optional) | GraphQL codegen types for third-party/integration APIs | `integration` |\n| `schema-admin` | Generated types for admin APIs (optional) | GraphQL codegen types specific to admin interface | `admin` |\n| `typescript-config` | Shared TypeScript configuration | TSConfig files, build settings | All applications and packages |\n\n## Infrastructure \u0026 Deployment\n\n\u003e **Work in Progress** - This section is under development\n\n### Infrastructure as Code\n\n#### `infra/`\n\n- **Technology**: Bicep templates\n- **Purpose**: Azure resource definitions\n- **Contents**: Resource groups, Function Apps, App Services, databases, networking\n\n### Deployment Templates\n\n#### `deploy/templates/`\n\n- **Purpose**: Reusable Azure Pipeline templates\n- **Contents**: Build, test, and deployment pipeline definitions\n- **Benefits**: Consistent deployment patterns across applications\n\n## Development Tools\n\n\u003e **Work in Progress** - This section is under development\n\nThis repository includes several development tools to maintain code quality and consistency:\n\n### Code Quality\n\n- **Biome**: Linting and formatting\n- **Lefthook**: Git hooks for pre-commit checks\n- **GitVersion**: Semantic versioning based on Git history\n\n### Build System\n\n- **Turbo**: Monorepo task orchestration\n- **pnpm Workspaces**: Package management and dependency resolution\n\n## Getting Started\n\n### Prerequisites\n\n- Git\n- Basic understanding of Azure services\n- Azure subscription (for deployment)\n\n### Setup\n\n#### Automated Setup (Recommended)\n\nRun the setup script to automatically install all required tools and dependencies:\n\n**Linux/macOS:**\n\n```sh\n./setup.sh\n```\n\n**Windows:**\n\n```powershell\n.\\setup.ps1\n```\n\nThe setup script will:\n\n- Install prerequisites (Homebrew on macOS)\n- Install Node Version Manager (NVM)\n- Install Node.js version from `.nvmrc`\n- Enable Corepack for package manager management\n- Install pnpm via Corepack\n- Install Azure Functions Core Tools\n- Install Docker (optional)\n\n#### Manual Setup\n\nIf you prefer manual installation:\n\n1. **Install Node.js** (version specified in `.nvmrc`)\n2. **Enable Corepack and install pnpm**\n\n   ```sh\n   corepack enable\n   corepack prepare pnpm@latest --activate\n   ```\n\n3. **Install Azure Functions Core Tools**\n\n   See [Azure Functions Core Tools documentation](https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local)\n\n4. **Clone and setup the repository**\n\n   ```sh\n   git clone https://github.com/shellicar/reference-enterprise.git\n   cd reference-enterprise\n   pnpm install\n   pnpm build\n   ```\n\n### Development\n\nOnce setup is complete, you can start developing:\n\n```sh\n# Start the API\npnpm --filter api dev\n\n# Start the web application\npnpm --filter webapp dev\n\n# Build all packages\npnpm build\n\n# Run tests\npnpm test\n```\n\n### Architecture Decisions\n\nThis structure provides:\n\n- **Clear separation** between user-facing and internal services\n- **Shared code** through common packages\n- **Scalable architecture** that can grow with application complexity\n- **Consistent development** patterns across all applications\n- **Flexible deployment** options for different application types\n\n## Architecture Approach\n\nThis 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.\n\n### Why Vertical Slices?\n\n**Benefits:**\n\n- **High cohesion** - Feature logic stays together\n- **Team independence** - Developers can work on different features without conflicts\n- **Easy to understand** - Business logic is contained and traceable\n- **Better pull requests** - Code changes are colocated, making reviews easier to follow\n- **Deployment flexibility** - Features can be developed and tested independently\n\n**Trade-offs:**\n\n- **Some code duplication** - Accept duplication when it keeps features independent\n- **Consistency overhead** - Requires discipline to maintain standards across slices\n- **Cross-cutting changes** - Security or infrastructure updates touch multiple slices\n\n### Database Considerations\n\nUsing document databases (Cosmos DB NoSQL, MongoDB) aligns well with vertical slices:\n\n- Features can model data as standalone documents or nested within parent entities\n- Less coupling through shared database schemas\n- Natural fit for feature-based data modelling\n\n### Team Approach\n\nThis architecture works best with teams that:\n\n- Communicate effectively and coordinate when needed\n- Recognize when duplication becomes problematic and refactor accordingly\n- Balance feature independence with shared concerns\n- Understand that **no architecture is perfect** - there are always trade-offs\n\n---\n\nThis enterprise reference provides a solid foundation for Azure application workloads with clear architectural boundaries and room for growth as applications mature.\n\n*This README was created with the assistance of [GitHub Copilot][copilot].*\n\n[nvm]: https://github.com/nvm-sh/nvm\n[pnpm]: https://pnpm.io\n[docker]: https://www.docker.com\n[copilot]: https://github.com/features/copilot\n[biome]: https://biomejs.dev\n[typescript]: https://www.typescriptlang.org\n[node]: https://nodejs.org/en\n[npm]: https://www.npmjs.com\n[tailwind]: https://tailwindcss.com\n[vite]: https://vitejs.dev\n[azure-functions]: https://www.npmjs.com/package/@azure/functions\n[graphql]: https://www.npmjs.com/package/graphql\n[nuxt]: https://nuxtjs.org\n[opentelemetry]: https://opentelemetry.io\n[zod]: https://github.com/colinhacks/zod\n[js-joda]: https://js-joda.github.io/js-joda\n[vscode]: https://code.visualstudio.com\n[vitest]: https://github.com/vitest-dev/vitest\n[tsx]: https://github.com/privatenumber/tsx\n[winston]: https://github.com/winstonjs/winston\n[esbuild]: https://esbuild.github.io\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshellicar%2Freference-enterprise","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshellicar%2Freference-enterprise","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshellicar%2Freference-enterprise/lists"}