OpenParable
Skip to content
← Back to skills

App Architecture

Development
app-architecture

App Architecture is an Agent Skill for development published in the growilabs/growi repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

GROWI main application (apps/app) architecture, directory structure, and design patterns. Auto-invoked when working in apps/app.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/growilabs/growi/blob/HEAD/apps/app/.claude/skills/app-architecture/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/app-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.

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

  1. Create features/{feature-name}/
  2. Define interfaces in interfaces/
  3. Implement server logic in server/ (models, routes, services)
  4. Implement client logic in client/ (components, hooks, states)
  5. 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);
});

State Management

  • Jotai: UI state (modals, forms) in states/
  • SWR: Server data (pages, users) in stores-universal/

For detailed patterns, see app-specific-patterns skill.

Design Principles

  1. Feature Isolation: New features self-contained in features/
  2. Server-Client Separation: Prevent server code bundled into client
  3. API-First: Define OpenAPI specs before implementation
  4. Type-Driven: Define interfaces before implementation
  5. Progressive Migration: Gradually move legacy code to features/

Legacy Migration

Legacy directories (components/, server/models/, client/) should be gradually migrated to features/:

  • New features → features/
  • Bug fixes → Can stay in legacy
  • Refactoring → Move to features/

Summary

  1. New features: features/{feature-name}/ structure
  2. Server-client separation: Keep separate
  3. API-first: OpenAPI specs for API v3
  4. State: Jotai (UI) + SWR (server data)
  5. Progressive migration: No rush for stable legacy code