Agent Package Architecture

The @ever-works/agent package is the core business logic layer of the Ever Works platform. It is a private NestJS package that encapsulates all work generation, AI orchestration, plugin management, and data handling logic. The API application (apps/api) consumes this package as a workspace dependency.

Package Overview

Property	Value
Package name	`@ever-works/agent`
Framework	NestJS 11 with SWC compiler
Build	`nest build -b swc` + `tsc -p tsconfig.types.json` for declarations
Test framework	Jest (26 suites, 719+ tests)
Workspace deps	`@ever-works/contracts`, `@ever-works/plugin`
Key libraries	TypeORM, Zod, LangChain, Ajv, superjson, isomorphic-git

Module Areas

The agent package exposes 27 sub-module entry points via the exports field in package.json. Each export maps to a distinct module area within src/:

Export Path	Source Work	Purpose
`./generators`	`src/generators/`	Three-stage content generation (data, markdown, website)
`./database`	`src/database/`	TypeORM entities, repositories, and database module
`./dto`	`src/dto/`	Data Transfer Objects for API validation
`./entities`	`src/entities/`	TypeORM entity definitions (Work, User, etc.)
`./git`	(see Facades + Utils)	Git operations — re-exported from `facades/git.facade.ts` and `utils/git-repository.utils.ts`
`./work-operations`	`src/work-operations/`	Low-level work CRUD operations
`./items-generator`	`src/items-generator/`	Item generation DTOs and utilities
`./tasks`	`src/tasks/`	Background task definitions
`./events`	`src/events/`	Domain event classes (NestJS EventEmitter)
`./services`	`src/services/`	Work service layer (14 services)
`./onboarding`	`src/onboarding/`	Account onboarding adapters (GitHub-app + work import)
`./subscriptions`	`src/subscriptions/`	Subscription, plan, and billing-ledger logic
`./config`	`src/config/`	Configuration constants and helpers
`./constants`	`src/constants/`	Shared cross-module constants
`./cache`	`src/cache/`	Cache management utilities
`./notifications`	`src/notifications/`	Notification system
`./activity-log`	`src/activity-log/`	Per-user audit trail + Jitsu analytics dispatcher
`./import`	`src/import/`	Data import functionality
`./works-config`	`src/works-config/`	`works.yml` parser, validator, and writer
`./facades`	`src/facades/`	Facade services for plugin capabilities
`./plugins`	`src/plugins/`	Plugin registry, loader, and settings
`./pipeline`	`src/pipeline/`	Pipeline builder, orchestrator, and executors
`./utils`	`src/utils/`	Shared utility functions
`./community-pr`	`src/community-pr/`	Community pull request management
`./comparison-generator`	`src/comparison-generator/`	A-vs-B comparison page generation
`./template-catalog`	`src/template-catalog/`	Built-in + custom website-template registry
`./account-transfer`	`src/account-transfer/`	Account export/import + GitHub-backed account sync

Work Structure

packages/agent/src/
├── account-transfer/         # Account export / import / GitHub-backed sync
├── activity-log/             # Per-user audit trail + analytics dispatcher
├── cache/                    # Cache management
├── community-pr/             # Community PR handling
├── comparison-generator/     # Item comparison generation
├── config/                   # Configuration constants
├── constants/                # Shared cross-module constants
├── database/                 # TypeORM database module
├── dto/                      # Data Transfer Objects
├── entities/                 # TypeORM entities
├── events/                   # Domain events
├── facades/                  # Capability facades (AI, Search, Git, …)
├── generators/               # Content generation pipeline
│   ├── data-generator/       # Data generation (items, categories)
│   ├── markdown-generator/   # Markdown/README generation
│   └── website-generator/    # Website repo generation
├── import/                   # Data import logic
├── items-generator/          # Item generation DTOs
├── notifications/            # Notification system
├── onboarding/               # Onboarding adapters (account + work)
├── pipeline/                 # Plugin-driven pipeline system
│   ├── validators/           # Pipeline result validation
│   └── __tests__/            # Pipeline test suite
├── plugins/                  # Plugin system core
│   ├── repositories/         # Plugin data repositories
│   └── services/             # Plugin registry, settings, loader
├── services/                 # Work service layer
│   ├── types/                # Service type definitions
│   ├── utils/                # Service utilities
│   └── __tests__/            # Service tests
├── subscriptions/            # Subscription, plan, and ledger services
├── tasks/                    # Background task definitions
├── template-catalog/         # Built-in + custom website-template registry
├── types/                    # Public type re-exports
├── utils/                    # Shared utilities (incl. git-repository helpers)
├── work-operations/          # Low-level work CRUD operations
└── works-config/             # `works.yml` parser, validator, and writer

NestJS Module Structure

The agent package follows NestJS module composition. Each major area defines its own Module class that declares providers and exports:

Key Module Relationships

WorkModule is the primary service module, importing generators, facades, and infrastructure modules. It provides 14 work-related services covering lifecycle, generation, scheduling, membership, taxonomy, and more.
PipelineModule provides the pipeline builder, orchestrator, and executors. It imports FacadesModule to give pipeline steps access to AI, search, and other capabilities.
FacadesModule provides 8 facade services that abstract plugin capabilities. It imports DatabaseModule for work-plugin mappings.

How the API Consumes the Agent Package

The API application (apps/api) imports agent modules into its own NestJS module tree:

// apps/api imports agent modules
import { WorkModule } from '@ever-works/agent/services';
import { PipelineModule } from '@ever-works/agent/pipeline';
import { FacadesModule } from '@ever-works/agent/facades';

The API provides HTTP controllers that delegate to agent services. For example, the works controller calls WorkGenerationService which in turn uses the PipelineOrchestratorService to execute the generation pipeline.

Service Layer

The services/ directory contains 19 specialized services that form the domain logic layer:

Service	Responsibility
`WorkLifecycleService`	Create, update, delete works
`WorkGenerationService`	Orchestrate full generation flow
`WorkQueryService`	Query and list works
`WorkDetailService`	Manage work details and metadata
`WorkOwnershipService`	Handle ownership and permissions
`WorkMemberService`	Manage work members
`WorkScheduleService`	CRON-based scheduled regeneration
`WorkScheduleDispatcherService`	Dispatch scheduled jobs
`WorkImportService`	Import data from external sources
`WorkAdvancedPromptsService`	Custom AI prompt management
`WorkTaxonomyService`	Category and tag management
`WorkWebsiteRepositoryStateService`	Track website-repo provisioning + sync state
`WorksManifestService`	Resolve and write the canonical `works.yml` manifest
`RepositoryManagementService`	Git repository lifecycle
`GeneratorFormSchemaService`	Dynamic form schema generation
`ItemHealthService`	Per-item source health checks (URL liveness, status mapping)
`ItemSourceValidationSchedulerService`	Schedules item source validation runs
`StateMarkerService`	Persists generator/import state markers in the data repository
`WebhookDeliveryService`	Delivers outbound webhooks for domain events

Dependencies

The agent package depends on two workspace packages:

@ever-works/contracts -- Shared TypeScript types for items, domains, forms, and API DTOs. Used throughout the agent for type-safe data structures.
@ever-works/plugin -- Plugin system contracts, abstract base classes, and AI operation wrappers. Defines interfaces like IPipelinePlugin, IAiProviderPlugin, and event types.

External Dependencies

Category	Packages
Framework	`@nestjs/common`, `@nestjs/core`, `@nestjs/config`, `@nestjs/swagger`
Database	`@nestjs/typeorm`, `typeorm`, `better-sqlite3`, `pg`, `mysql2`
Validation	`zod`, `zod-to-json-schema`, `ajv`, `ajv-formats`, `class-validator`, `class-transformer`
AI	`@langchain/textsplitters`
Caching	`@nestjs/cache-manager`, `cache-manager`
Events	`@nestjs/event-emitter`
Utilities	`lodash`, `date-fns`, `github-slugger`, `semver`, `superjson`, `yaml`, `p-map`

Build and Test

# Development (watch mode)
cd packages/agent && pnpm dev

# Production build
cd packages/agent && pnpm build

# Run all tests
cd packages/agent && pnpm test

# Run specific test pattern
cd packages/agent && npx jest --testPathPattern='pipeline'

# Coverage report
cd packages/agent && pnpm test:cov

The build produces two outputs: SWC-compiled JavaScript in dist/ and TypeScript declaration files via tsconfig.types.json. This dual-build approach gives fast compilation with SWC while maintaining full type information for consumers.

Package Overview​

Module Areas​

Work Structure​

NestJS Module Structure​

Key Module Relationships​

How the API Consumes the Agent Package​

Service Layer​

Dependencies​

External Dependencies​

Build and Test​