npm package: @ortha/server-projects
Description: Projects backend for the Ortha server — CRUD API for projects with many-to-many user-project associations, permission-based access control, and Sequelize schema definitions.
Latest version: 0.0.4

# @ortha/server-projects

Projects backend for the Ortha server — CRUD API for projects with many-to-many user-project associations, permission-based access control, and Sequelize schema definitions.

## Installation

Internal monorepo dependency — import directly:

```ts
import { projectsServerPlugin, projectsSchema } from '@ortha/server-projects';
import type { ProjectModel, CreateProjectBody } from '@ortha/server-projects';
```

## Usage

### Registering the plugin

```ts
import { bootstrap } from '@ortha/server-platform-bootstrap';
import { databasePlugin } from '@ortha/server-platform-database';
import { identitySchema, identityServerPlugin } from '@ortha/server-identity';
import { projectsSchema, projectsServerPlugin } from '@ortha/server-projects';

await bootstrap({
    config: bootstrapConfig,
    plugins: [
        databasePlugin({
            ...dbConfig,
            schemas: [identitySchema, projectsSchema]
        }),
        identityServerPlugin(jwtConfig),
        projectsServerPlugin()
    ]
});
```

## Routes

| Method | Path                | Auth | Permissions            | Description          |
| ------ | ------------------- | ---- | ---------------------- | -------------------- |
| POST   | `/api/projects`     | Yes  | `create:admin:project` | Create a new project |
| GET    | `/api/projects`     | Yes  | —                      | List all projects    |
| GET    | `/api/projects/:id` | Yes  | —                      | Get project by ID    |
| PATCH  | `/api/projects/:id` | Yes  | `update:admin:project` | Update project       |
| DELETE | `/api/projects/:id` | Yes  | `delete:admin:project` | Soft-delete project  |

## API Reference

### Plugin & Schema

| Export                   | Kind    | Description                                     |
| ------------------------ | ------- | ----------------------------------------------- |
| `projectsServerPlugin()` | factory | Fastify plugin — registers project routes       |
| `projectsSchema`         | schema  | Sequelize `SchemaDefinition` for project models |

### Types

| Export              | Kind | Description                         |
| ------------------- | ---- | ----------------------------------- |
| `ProjectModel`      | type | Sequelize project model type        |
| `UserProjectModel`  | type | Sequelize join model (user-project) |
| `ProjectResponse`   | type | API response shape                  |
| `CreateProjectBody` | type | Create request body                 |
| `UpdateProjectBody` | type | Update request body                 |

## Sequelize Models

| Model         | Description                                         |
| ------------- | --------------------------------------------------- |
| `Project`     | Project record (name, slug, description, status)    |
| `UserProject` | Join table linking users to projects (many-to-many) |

## Internal Structure

```
src/lib/
├── types/index.ts                          # Request/response types
├── schema/index.ts                         # Sequelize models (Project, UserProject)
├── projectsServerPlugin/index.ts           # Fastify plugin factory
├── controllers/                            # Route handlers (one per folder)
└── services/
    ├── index.ts                            # Barrel
    ├── utils/
    │   ├── toProjectResponse/index.ts      # Raw project → API response mapper
    │   ├── modelToJSON/index.ts            # Safe Sequelize .toJSON() wrapper
    │   └── bulkCreateSlugs/index.ts        # Bulk create junction rows
    ├── createProject/index.ts              # Create project + assign members
    ├── listProjects/index.ts               # List user's projects
    ├── getProjectById/index.ts             # Get single project by ID
    ├── updateProject/index.ts              # Update project fields + associations
    └── deleteProject/index.ts              # Soft-delete project
```

## Key Patterns

- Each service is a plain async function: `serviceName(deps)(args)`.
- `UserProjectModel` is a join table for many-to-many user-project associations.
- Schema `associate()` wires relations to identity models via the shared `ModelRegistry`.
- Routes are protected with `authHook` and `permissionHook` from `@ortha/server-identity`.
- All CRUD operations are scoped to user membership.

## Dependencies

- `@ortha/server-platform-database` — `SchemaDefinition`, `ModelRegistry` types
- `@ortha/server-identity` — `authHook`, `permissionHook`, `getRequestUser`
- `@ortha/server-utils` — error response builders

## Building

```bash
nx build server-projects
```