Skip to content

Commit 8c5fc6b

Browse files
rdonigianrdonigian
committed
create ai guidelines
1 parent 0d71a8b commit 8c5fc6b

File tree

2 files changed

+198
-0
lines changed

2 files changed

+198
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# CORD API Development Guidelines
2+
3+
This document provides guidelines for developers working on the CORD API v3 project, a backend built with NestJS, GraphQL, and Neo4j/Gel, using NodeJS and Docker.
4+
5+
### Code Style
6+
7+
The project uses ESLint and Prettier for code formatting and linting:
8+
9+
- Run `yarn lint` to check and fix linting issues.
10+
- Run `yarn format` to format code using Prettier.
11+
- Enforce TypeScript strict mode (`tsconfig.json` with `strict: true`).
12+
13+
### GraphQL
14+
15+
The project uses NestJS with GraphQL (graphql-yoga):
16+
17+
- GraphQL schema is generated in `schema.graphql` via `yarn gel:gen`.
18+
- Resolvers are defined in `*.resolver.ts` files in `src/components`.
19+
- DTOs (Data Transfer Objects) are defined in `*.dto.ts` files.
20+
- Only access properties defined in DTOs or interfaces.
21+
22+
### Database
23+
24+
The API is transitioning from Neo4j to Gel:
25+
26+
- Neo4j is used with the `cypher-query-builder` library for queries.
27+
- Gel is the next-gen database replacing Neo4j.
28+
- Create migrations with `yarn gel:migration` to update the database schema.
29+
- Generate seed data with `yarn gel:seed` for testing or development.
30+
31+
### Project Structure
32+
33+
- `src/`: Source code
34+
- `src/common/`: Common utilities, decorators, and TypeScript interfaces.
35+
- `src/components/`: Feature-specific modules (e.g., `user`, `order`), containing resolvers, services, DTOs, and tests subfolders.
36+
- `src/core/`: Core functionality, such as database connections and GraphQL setup.
37+
- `test/`: E2E tests
38+
- `test/utility/`: Test utilities (e.g., test app setup).
39+
- `dbschema/`: Database schema definitions and migrations.
40+
41+
### Coding Standards
42+
43+
- Use single quotes for strings, 2 spaces for indentation.
44+
- Prefer async/await for asynchronous operations.
45+
- Use `const` for constants, minimize `let` usage (e.g., except in try/catch).
46+
- Use destructuring for objects/arrays, template literals for strings.
47+
- Follow SOLID principles for modular, reusable, maintainable code.
48+
- Avoid code duplication, deeply nested statements, hard-coded values.
49+
- Use constants/enums instead of magic numbers/strings.
50+
- Avoid mutations:
51+
- Prefer `const` over `let`.
52+
- Use spread syntax (e.g., `{ ...object, foo: 'bar' }`) instead of modifying objects.
53+
- Use strict TypeScript:
54+
- Define all object shapes in DTOs (`*.dto.ts`) or interfaces in `src/common`.
55+
- Use type guards for safe property access (e.g., `if ('foo' in obj)`).
56+
57+
### GraphQL Guidelines
58+
59+
- Define resolvers in `*.resolver.ts` with clear input/output types.
60+
- Use DTOs for input validation and response shaping.
61+
- Avoid overfetching; include only necessary fields in queries.
62+
63+
### Database Guidelines
64+
65+
- Write Cypher queries for Neo4j using `cypher-query-builder` for type safety.
66+
- Create Gel migrations for schema changes (`yarn gel:migration`).
67+
- Validate query results against defined DTOs or interfaces.
68+
- Avoid direct database mutations outside services; encapsulate in `*.service.ts`.
69+
70+
### Tagged Comments
71+
72+
- Use `// ai tag` to mark code for reference:
73+
- `example`: Best practice or model code.
74+
- `edge-case`: Necessary deviation from standards.
75+
- `best-practice`: Adherence to coding standards.
76+
- `anti-pattern`: Code to avoid (pending refactor).
77+
- `todo`: Needs improvement or refactoring.
78+
- `workaround`: Temporary fix for a limitation.
79+
- `performance`: Optimized code.
80+
- `security`: Security-critical code.
81+
- `test`: Exemplary test case.
82+
- `type-safety`: Safe property access.
83+
- Optionally add notes after the tag (e.g., `// ai example Type-safe resolver`).
84+
- Search tags with `git grep "ai "` to collect examples.
85+
86+
## Project Structure
87+
88+
- Place GraphQL resolvers in `src/components/*/resolver.ts`.
89+
- Place services in `src/components/*/service.ts`.
90+
- Place DTOs in `src/components/*/dto/*.dto.ts`.
91+
- Place interfaces in `src/common`.
92+
- Place unit tests in `src/components/*/tests/*.spec.ts`.
93+
- Place E2E tests in `test/*.e2e-spec.ts`.
94+
95+
## Coding Standards
96+
97+
- Use camelCase for variables/functions, PascalCase for classes/interfaces/DTOs, kebab-case for files/folders.
98+
- Use single quotes, 2-space indentation, async/await, and `const` over `let`.
99+
- Use strict TypeScript with DTOs (`*.dto.ts`) or interfaces (`src/common`).

‎.junie/guidelines.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# CORD API Development Guidelines
2+
3+
This document provides guidelines for developers working on the CORD API v3 project, a backend built with NestJS, GraphQL, and Neo4j/Gel, using NodeJS and Docker.
4+
5+
### Code Style
6+
7+
The project uses ESLint and Prettier for code formatting and linting:
8+
9+
- Run `yarn lint` to check and fix linting issues.
10+
- Run `yarn format` to format code using Prettier.
11+
- Enforce TypeScript strict mode (`tsconfig.json` with `strict: true`).
12+
13+
### GraphQL
14+
15+
The project uses NestJS with GraphQL (graphql-yoga):
16+
17+
- GraphQL schema is generated in `schema.graphql` via `yarn gel:gen`.
18+
- Resolvers are defined in `*.resolver.ts` files in `src/components`.
19+
- DTOs (Data Transfer Objects) are defined in `*.dto.ts` files.
20+
- Only access properties defined in DTOs or interfaces.
21+
22+
### Database
23+
24+
The API is transitioning from Neo4j to Gel:
25+
26+
- Neo4j is used with the `cypher-query-builder` library for queries.
27+
- Gel is the next-gen database replacing Neo4j.
28+
- Create migrations with `yarn gel:migration` to update the database schema.
29+
- Generate seed data with `yarn gel:seed` for testing or development.
30+
31+
### Project Structure
32+
33+
- `src/`: Source code
34+
- `src/common/`: Common utilities, decorators, and TypeScript interfaces.
35+
- `src/components/`: Feature-specific modules (e.g., `user`, `order`), containing resolvers, services, DTOs, and tests subfolders.
36+
- `src/core/`: Core functionality, such as database connections and GraphQL setup.
37+
- `test/`: E2E tests
38+
- `test/utility/`: Test utilities (e.g., test app setup).
39+
- `dbschema/`: Database schema definitions and migrations.
40+
41+
### Coding Standards
42+
43+
- Use single quotes for strings, 2 spaces for indentation.
44+
- Prefer async/await for asynchronous operations.
45+
- Use `const` for constants, minimize `let` usage (e.g., except in try/catch).
46+
- Use destructuring for objects/arrays, template literals for strings.
47+
- Follow SOLID principles for modular, reusable, maintainable code.
48+
- Avoid code duplication, deeply nested statements, hard-coded values.
49+
- Use constants/enums instead of magic numbers/strings.
50+
- Avoid mutations:
51+
- Prefer `const` over `let`.
52+
- Use spread syntax (e.g., `{ ...object, foo: 'bar' }`) instead of modifying objects.
53+
- Use strict TypeScript:
54+
- Define all object shapes in DTOs (`*.dto.ts`) or interfaces in `src/common`.
55+
- Use type guards for safe property access (e.g., `if ('foo' in obj)`).
56+
57+
### GraphQL Guidelines
58+
59+
- Define resolvers in `*.resolver.ts` with clear input/output types.
60+
- Use DTOs for input validation and response shaping.
61+
- Avoid overfetching; include only necessary fields in queries.
62+
63+
### Database Guidelines
64+
65+
- Write Cypher queries for Neo4j using `cypher-query-builder` for type safety.
66+
- Create Gel migrations for schema changes (`yarn gel:migration`).
67+
- Validate query results against defined DTOs or interfaces.
68+
- Avoid direct database mutations outside services; encapsulate in `*.service.ts`.
69+
70+
### Tagged Comments
71+
72+
- Use `// ai tag` to mark code for reference:
73+
- `example`: Best practice or model code.
74+
- `edge-case`: Necessary deviation from standards.
75+
- `best-practice`: Adherence to coding standards.
76+
- `anti-pattern`: Code to avoid (pending refactor).
77+
- `todo`: Needs improvement or refactoring.
78+
- `workaround`: Temporary fix for a limitation.
79+
- `performance`: Optimized code.
80+
- `security`: Security-critical code.
81+
- `test`: Exemplary test case.
82+
- `type-safety`: Safe property access.
83+
- Optionally add notes after the tag (e.g., `// ai example Type-safe resolver`).
84+
- Search tags with `git grep "ai "` to collect examples.
85+
86+
## Project Structure
87+
88+
- Place GraphQL resolvers in `src/components/*/resolver.ts`.
89+
- Place services in `src/components/*/service.ts`.
90+
- Place DTOs in `src/components/*/dto/*.dto.ts`.
91+
- Place interfaces in `src/common`.
92+
- Place unit tests in `src/components/*/tests/*.spec.ts`.
93+
- Place E2E tests in `test/*.e2e-spec.ts`.
94+
95+
## Coding Standards
96+
97+
- Use camelCase for variables/functions, PascalCase for classes/interfaces/DTOs, kebab-case for files/folders.
98+
- Use single quotes, 2-space indentation, async/await, and `const` over `let`.
99+
- Use strict TypeScript with DTOs (`*.dto.ts`) or interfaces (`src/common`).

0 commit comments

Comments
 (0)