Project Architecture
Developmentproject-architectureProject Architecture is an Agent Skill for development published in the BidingCC/BuildingAI repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
BuildingAI monorepo project structure and architecture guide. Use when AI needs to understand project organization, locate files, understand package relationships, find where specific functionality is implemented, or navigate the codebase structure. Essential for any development task that requires understanding the project layout, import patterns, module organization, or cross-package dependencies.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/BidingCC/BuildingAI/blob/HEAD/skills/project-architecture/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/project-architecture, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
BuildingAI Project Architecture
Comprehensive guide to BuildingAI monorepo structure, packages, and development patterns.
When to Use
Use this skill when you need to:
- Locate where specific functionality is implemented
- Understand package relationships and dependencies
- Find the correct import paths and patterns
- Navigate module organization and structure
- Understand development patterns and conventions
- Know what each package provides and how to use it
Instructions
Understanding the Monorepo Structure
The BuildingAI project is a pnpm workspace monorepo with the following structure:
buildingai/
├── packages/
│ ├── @buildingai/ # Shared packages
│ │ ├── ai-sdk/ # AI SDK (legacy)
│ │ ├── ai-sdk-new/ # AI SDK (Vercel AI SDK 6.x)
│ │ ├── base/ # BaseController, BaseService
│ │ ├── cache/ # CacheService, RedisService
│ │ ├── config/ # Configuration management
│ │ ├── constants/ # Shared constants
│ │ ├── db/ # TypeORM, entities, migrations
│ │ ├── decorators/ # Custom decorators
│ │ ├── di/ # Dependency injection utilities
│ │ ├── dict/ # Dictionary/configuration management
│ │ ├── dto/ # Shared DTOs
│ │ ├── errors/ # HttpErrorFactory
│ │ ├── eslint-config/ # ESLint configuration
│ │ ├── extension-sdk/ # Extension development SDK
│ │ ├── logger/ # Logging utilities
│ │ ├── pipe/ # Validation pipes
│ │ ├── types/ # TypeScript type definitions
│ │ ├── typescript-config/ # TypeScript configurations
│ │ ├── upgrade/ # Version upgrade scripts
│ │ ├── utils/ # Utility functions, HTTP client
│ │ ├── web/ # Frontend shared packages
│ │ │ ├── hooks/ # React hooks
│ │ │ ├── http/ # HTTP client
│ │ │ ├── services/ # Frontend services
│ │ │ ├── stores/ # State management (Pinia)
│ │ │ ├── types/ # TypeScript types
│ │ │ └── ui/ # UI components
│ │ ├── di/ # Dependency injection utilities
│ │ └── wechat-sdk/ # WeChat integration SDK
│ ├── api/ # Main NestJS API application
│ ├── core/ # Reusable business logic modules
│ ├── cli/ # CLI tooling
│ └── client/ # Desktop client (Tauri + React)
├── skills/ # AI skills for development guidance
├── extensions/ # Plugin extensions (runtime loaded)
├── public/ # Static web assets
└── scripts/ # Build and utility scripts
Using Reference Files
For detailed information about each package, consult the corresponding reference file in
references/:
@buildingai Packages:
references/base.md- BaseController, BaseServicereferences/cache.md- CacheService, RedisServicereferences/config.md- Configuration managementreferences/constants.md- Shared constantsreferences/db.md- Database layer (TypeORM, entities)references/decorators.md- Custom decoratorsreferences/dict.md- Dictionary managementreferences/dto.md- Shared DTOsreferences/errors.md- Error handlingreferences/logger.md- Logging utilitiesreferences/utils.md- Utility functions, HTTP clientreferences/ai-sdk.md- AI SDK packagesreferences/web.md- Frontend packagesreferences/extension-sdk.md- Extension SDKreferences/pipe.md- Validation pipesreferences/types.md- TypeScript typesreferences/upgrade.md- Version upgrade scriptsreferences/di.md- Dependency injection utilitiesreferences/wechat-sdk.md- WeChat integration SDK
Main Packages:
references/api.md- Main NestJS API applicationreferences/core.md- Reusable business logicreferences/cli.md- CLI toolingreferences/client.md- Desktop client
Load these reference files when you need detailed information about a specific package's exports, usage patterns, or implementation details.
Import Patterns
Backend (API/Core) Import Order:
@buildingai/*packages@nestjs/*packages@common/*(API only)@modules/*(API only)@core/*(API only)- Third-party packages
- Relative paths
Path Aliases (API):
@common/*→src/common/*@modules/*→src/modules/*@core/*→src/core/*@assets/*→src/assets/*
Development Patterns
Service Pattern:
- Extend
BaseService<Entity>from@buildingai/basefor CRUD operations - Use dependency injection with
@InjectRepository()for repositories - See
references/base.mdfor available methods and features
Controller Pattern:
- Use
@ConsoleController(path, groupName)for admin APIs (auto auth + permissions) - Use
@WebController(path)for frontend APIs (requires auth by default) - Use
@Playground()decorator to get current user - See
references/decorators.mdandreferences/api.mdfor details
**Module Structure: src/modules/{module-name}/ with controllers, services, and DTOs
Quick Navigation
When implementing features, reference the appropriate package:
- Authentication:
references/decorators.md(@Playground()),references/api.md(guards) - Database:
references/db.md(entities),references/base.md(BaseService CRUD) - Error Handling:
references/errors.md(HttpErrorFactory) - Caching:
references/cache.md(CacheService, RedisService) - File Upload:
references/core.md(upload services) - AI Functionality:
references/ai-sdk.md,references/api.md(AI modules) - Frontend:
references/web.md(services, stores, UI components)
Skills Integration
This skill works with other skills:
postgresql-table-design- For database schema designfrontend-design- For frontend UI developmentai-sdk- For AI functionality implementation
When implementing features, reference the appropriate package reference file to understand what's available and how to use it.