Agent Skills › growilabs/growi › app-architecture

app-architecture

GitHub

定义GROWI主应用的全栈架构、目录结构与特性模块化规范，指导新代码开发及遗留代码迁移。

apps/app/.claude/skills/app-architecture/SKILL.md growilabs/growi

触发场景

在 apps/app 目录下工作询问应用架构或目录结构需要创建新功能模块

安装

npx skills add growilabs/growi --skill app-architecture -g -y

更多选项

非标准路径

npx skills add https://github.com/growilabs/growi/tree/master/apps/app/.claude/skills/app-architecture -g -y

不安装直接使用

npx skills use growilabs/growi@app-architecture

指定 Agent (Claude Code)

npx skills add growilabs/growi --skill app-architecture -a claude-code -g -y

安装 repo 全部 skill

npx skills add growilabs/growi --all -g -y

预览 repo 内 skill

npx skills add growilabs/growi --list

SKILL.md

Frontmatter

{
    "name": "app-architecture",
    "description": "GROWI main application (apps\/app) architecture, directory structure, and design patterns. Auto-invoked when working in apps\/app.",
    "user-invocable": false
}

App Architecture (apps/app)

The main GROWI application is a full-stack Next.js application with Express.js backend and MongoDB database.

For technology stack details, see the global tech-stack skill.

Directory Structure

apps/app/src/
├── pages/                 # Next.js Pages Router (*.page.tsx)
├── features/             # Feature modules (recommended for new code)
│   └── {feature-name}/
│       ├── index.ts      # Public exports
│       ├── interfaces/   # TypeScript types
│       ├── server/       # models/, routes/, services/
│       └── client/       # components/, states/, hooks/
├── server/               # Express server (legacy)
│   ├── models/           # Mongoose models
│   ├── routes/apiv3/     # RESTful API v3
│   └── services/         # Business logic
├── components/           # React components (legacy)
├── states/               # Jotai atoms
└── stores-universal/     # SWR hooks

Feature-Based Architecture

Organize code by business feature rather than by technical layer:

❌ Layer-based (old):          ✅ Feature-based (new):
├── models/User.ts             ├── features/user/
├── routes/user.ts             │   ├── server/models/User.ts
├── components/UserList.tsx    │   ├── server/routes/user.ts
                               │   └── client/components/UserList.tsx

Creating a New Feature

Create features/{feature-name}/
Define interfaces in interfaces/
Implement server logic in server/ (models, routes, services)
Implement client logic in client/ (components, hooks, states)
Export public API through index.ts

Entry Points

Server: server/app.ts - Express + Next.js initialization
Client: pages/_app.page.tsx - Jotai + SWR providers
Wiki Pages: pages/[[...path]]/index.page.tsx - Catch-all route (SSR)

API Design (RESTful API v3)

Routes in server/routes/apiv3/ with OpenAPI specs:

/**
 * @openapi
 * /api/v3/pages/{id}:
 *   get:
 *     summary: Get page by ID
 */
router.get('/pages/:id', async (req, res) => {
  const page = await PageService.findById(req.params.id);
  res.json(page);
});