From 0ef07bf126bf5c88b3a26e6d955a777339267bfd Mon Sep 17 00:00:00 2001
From: Krupa Hebbar <krupa.h@fyle.in>
Date: Thu, 30 Apr 2026 13:41:27 +0530
Subject: [PATCH] add claude.md

---
 CLAUDE.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 108 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..36034e405
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,108 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+`fyle-platform-docs` is the OpenAPI documentation repository for the Sage Expense Management Platform APIs, published at [docs.fylehq.com](https://docs.fylehq.com). It uses Redocly CLI to lint and bundle modular OpenAPI 3.0 specs, and Stoplight Prism for mock servers.
+
+## Prerequisites
+
+- Node.js >= v14.15.3
+- Redocly CLI: `npm install -g @redocly/openapi-cli`
+
+## Common Commands
+
+### Linting
+
+Lint any role's spec before committing changes:
+
+```bash
+openapi lint src/admin/openapi.yaml
+openapi lint src/spender/openapi.yaml
+openapi lint src/approver/openapi.yaml
+openapi lint src/authorization/openapi.yaml
+openapi lint src/hod/openapi.yaml
+openapi lint src/hop/openapi.yaml
+openapi lint src/common/openapi.yaml
+openapi lint src/accountant/openapi.yaml
+openapi lint src/super_admin/openapi.yaml
+```
+
+### Bundling
+
+Bundle a role's modular spec into a single reference file (required before the mock server picks up changes):
+
+```bash
+openapi bundle -o reference/admin.yaml src/admin/openapi.yaml
+openapi bundle -o reference/spender.yaml src/spender/openapi.yaml
+# etc. — pattern: openapi bundle -o reference/<role>.yaml src/<role>/openapi.yaml
+```
+
+Bundling also runs automatically via GitHub Actions on push/PR to `main`.
+
+### Preview Docs
+
+```bash
+openapi preview-docs src/admin/openapi.yaml
+```
+
+### Mock Server
+
+The mock server reads from the bundled `reference/` files, so bundle first if you've made changes:
+
+```bash
+docker-compose up
+```
+
+| Role | Port |
+|---|---|
+| Admin | 4011 |
+| Spender | 4012 |
+| Approver | 4013 |
+| Common / Accountant / Super Admin | 4014 |
+| Manager | 4015 |
+
+## Deployment
+
+After a feature PR is merged to `main`, deploy to production by merging `main` into the `v1` branch:
+
+```bash
+git checkout main && git pull origin main
+git checkout v1 && git pull origin v1
+git merge main
+git push origin v1
+```
+
+## Architecture
+
+### Source specs (`src/`)
+
+Each user role has its own OpenAPI module:
+
+```
+src/
+├── <role>/
+│   ├── openapi.yaml      # Root spec — declares servers, tags, security, and $ref paths
+│   └── paths/            # One YAML file per endpoint, named <resource>[@<sub>].yaml
+├── components/
+│   ├── parameters/       # Shared query/header parameters
+│   └── schemas/          # Shared request/response schemas
+```
+
+Roles: `admin`, `spender`, `approver`, `authorization`, `common`, `accountant`, `hod`, `hop`, `owner`, `manager`, `super_admin`.
+
+Path files use `@` as a URL separator in filenames (e.g., `admin@expenses@bulk.yaml` → `POST /admin/expenses/bulk`).
+
+### Bundled specs (`reference/`)
+
+The `reference/` directory contains fully-resolved, single-file versions of each role's spec, generated by `openapi bundle`. These are what the mock server and docs platform consume. Do not edit these files directly — they are generated.
+
+### Docs content (`docs/`)
+
+Markdown files for conceptual documentation (auth flows, data API guide, event subscriptions, cluster/region routing, error reference). Structured via `toc.json`.
+
+## PR Requirements
+
+- Title must match: `^(fix|feat|test|chore|refactor|build):` (case-insensitive)
+- Description must contain a ClickUp link (`app.clickup.com`)