Skip to content

Commit 4721610

Browse files
MmagdyHafezZMmagdyHafezZ
committed
docs: introducing better docs, commit and pr conventions.
1 parent 27ab626 commit 4721610

File tree

8 files changed

+809
-371
lines changed

8 files changed

+809
-371
lines changed

‎.github/workflows/commit-messages.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
name: Commit message lint
2+
on:
3+
pull_request:
4+
types: [opened, synchronize, reopened]
5+
jobs:
6+
commitlint:
7+
runs-on: ubuntu-latest
8+
steps:
9+
- uses: actions/checkout@v4
10+
with: { fetch-depth: 0 }
11+
- name: Install deps
12+
run: |
13+
corepack enable
14+
yarn --version
15+
yarn install --immutable || yarn install
16+
- uses: wagoid/commitlint-github-action@v6
17+
with:
18+
configFile: commitlint.config.js

‎.github/workflows/pr-title.yml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
name: PR title lint
2+
on:
3+
pull_request_target:
4+
types: [opened, edited, synchronize]
5+
permissions:
6+
pull-requests: read
7+
jobs:
8+
lint:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: amannn/action-semantic-pull-request@v5
12+
with:
13+
types: |
14+
feat,fix,chore,docs,refactor,test,build,ci,perf
15+
requireScope: false
16+
env:
17+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.secrets.baseline‎

Lines changed: 4 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
"files": null,
44
"lines": null
55
},
6-
"generated_at": "2025-10-23T17:29:45Z",
6+
"generated_at": "2025-10-28T02:41:25Z",
77
"plugins_used": [
88
{
99
"name": "AWSKeyDetector"
@@ -149,7 +149,7 @@
149149
{
150150
"hashed_secret": "2c0580ffd7d80319531cf629f5e90f747b1386f1",
151151
"is_verified": false,
152-
"line_number": 2561,
152+
"line_number": 2570,
153153
"type": "Secret Keyword",
154154
"verified_result": null
155155
}
@@ -322,18 +322,11 @@
322322
],
323323
"docs/CONTRIBUTING.md": [
324324
{
325-
"hashed_secret": "1c2b0d17c738509518ecc6efa233ee6c10e724f2",
325+
"hashed_secret": "5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8",
326326
"is_verified": false,
327-
"line_number": 224,
327+
"line_number": 135,
328328
"type": "Basic Auth Credentials",
329329
"verified_result": null
330-
},
331-
{
332-
"hashed_secret": "f6b2b77f83ae6122acb0954c6502cf87b2c097c3",
333-
"is_verified": false,
334-
"line_number": 264,
335-
"type": "Secret Keyword",
336-
"verified_result": null
337330
}
338331
]
339332
},

‎README.md‎

Lines changed: 76 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,110 +1,90 @@
11
![Build Status](https://github.com/ibm-skills-network/mark/actions/workflows/release.yml/badge.svg)
22

3-
# Mark System
3+
# Mark
44

5-
## Overview
5+
**Mark** is an AI-powered educational assessment platform that automates grading, provides intelligent feedback, and supports multilingual learning at scale.
66

7-
Mark System is an advanced education technology platform that provides AI-assisted assessment and feedback capabilities for educational institutions. The system handles assignment creation, question management, student attempts, automated grading, and multilingual support.
7+
---
88

9-
## Key Features
10-
11-
- **AI-Assisted Grading**: Automated evaluation of various response types (text, file uploads, URLs)
12-
- **Multi-Format Assessments**: Support for multiple-choice, text, file upload, URL submission questions
13-
- **Multilingual Support**: Translation of assignments and questions into multiple languages
14-
- **Assignment Management**: Creation, editing, and publishing of assignments
15-
- **Attempt Tracking**: Monitoring student submissions and progress
16-
- **Job Status Monitoring**: Real-time tracking of long-running operations
17-
- **Reporting & Analytics**: Insights into student performance and system usage
18-
19-
## System Architecture
9+
## Quick Links
2010

21-
The Mark System is built on a modular, domain-driven architecture that separates concerns into distinct services and repositories. The system follows modern software engineering principles including the repository pattern, dependency injection, and service-oriented architecture.
11+
- [Getting Started](#getting-started)
12+
- [Key Features](#key-features)
13+
- [Technology Stack](#technology-stack)
14+
- [Contributing](./docs/CONTRIBUTING.md)
15+
- [Architecture Overview](#architecture-overview)
2216

23-
### Core Components
17+
---
2418

25-
#### Controllers
19+
## Getting Started
2620

27-
- **Assignment Controller**: Manages assignment CRUD operations
28-
- **Question Controller**: Handles question management
29-
- **Job Status Controller**: Tracks long-running processes
30-
- **Attempt Controller**: Processes student attempts and submissions
21+
### For Contributors
3122

32-
#### Services
23+
1. **Clone the repository**
3324

34-
- **Assignment Service**: Core business logic for assignments
35-
- **Question Service**: Question generation and management
36-
- **Translation Service**: Multilingual support
37-
- **Job Status Service**: Process monitoring and reporting
38-
- **Attempt Service**: Submission handling and grading
25+
```bash
26+
git clone https://github.com/ibm-skills-network/mark.git
27+
cd mark
28+
```
3929

40-
#### Repositories
30+
2. **Follow the setup guide**
31+
See [CONTRIBUTING.md](./docs/CONTRIBUTING.md) for detailed setup instructions, environment configuration, and development workflows.
4132

42-
- **Assignment Repository**: Data access for assignments
43-
- **Question Repository**: Data access for questions and variants
44-
- **Job Status Repository**: Data access for process tracking
33+
3. **Pick an issue**
34+
Browse the [project board](https://github.com/orgs/ibm-skills-network/projects/9) and assign yourself an issue.
4535

46-
#### LLM Integration
47-
48-
- **LLM Facade Service**: Abstraction layer for AI/ML providers
49-
- **Specialized Grading Services**: Purpose-built evaluators for different content types
50-
- **Prompt Processor**: Manages prompts for AI services
51-
- **Token Counter & Usage Tracker**: Monitors usage for optimization
52-
53-
## Technology Stack
36+
### For Users
5437

55-
- **Backend**: NestJS (TypeScript)
56-
- **Database**: PostgreSQL with Prisma ORM
57-
- **AI Integration**: OpenAI and other LLM providers
58-
- **Concurrency Management**: Bottleneck.js for rate limiting
59-
- **Testing**: Jest
38+
Mark is designed for educational institutions looking to scale their assessment capabilities with AI assistance. Contact the team for deployment options.
6039

61-
## Key Architectural Improvements
40+
---
6241

63-
Mark System V2 represents a significant evolution from the original architecture, with improvements in:
64-
65-
1. **Repository Pattern Implementation**:
66-
- Centralized data access logic
67-
- Improved testability and maintainability
42+
## Key Features
6843

69-
2. **Service Modularity**:
70-
- Specialized service components
71-
- Clear boundaries of responsibility
44+
- **AI-Assisted Grading** - Automated evaluation with customizable rubrics
45+
- **Multi-Format Support** - Text, file uploads, URLs, presentations, videos
46+
- **Multilingual** - Translate assignments and feedback into multiple languages
47+
- **Real-Time Progress** - Track grading jobs and student attempts
48+
- **Flexible Architecture** - Modular, extensible, and production-ready
7249

73-
3. **Enhanced Error Handling**:
74-
- Structured logging with stack traces
75-
- Error categorization and recovery strategies
50+
---
7651

77-
4. **Concurrency Management**:
78-
- Rate limiting with Bottleneck
79-
- Queue management for high-load operations
52+
## Technology Stack
8053

81-
5. **Intelligent Processing**:
82-
- Content change detection
83-
- Avoiding redundant operations
84-
- Batch processing for efficiency
54+
| Layer | Technology |
55+
| -------------- | -------------------------------------------- |
56+
| **Backend** | NestJS (TypeScript) |
57+
| **Database** | PostgreSQL + Prisma ORM |
58+
| **AI/LLM** | OpenAI GPT-4o, extensible to other providers |
59+
| **Messaging** | NATS |
60+
| **Testing** | Jest |
61+
| **Deployment** | Docker, GitHub Actions |
8562

86-
6. **Progress Tracking**:
87-
- Detailed job status reporting
88-
- Percentage-based completion indicators
63+
---
8964

90-
7. **Health Monitoring**:
91-
- System health checks
92-
- Recovery from stalled processes
65+
## Architecture Overview
9366

94-
### Contribution Guidelines
67+
Mark follows a **domain-driven, service-oriented architecture** with clear separation of concerns:
9568

96-
Contributions are welcome.
69+
### Layers
9770

98-
First, pick up an issue from the [board](https://github.com/orgs/ibm-skills-network/projects/9) and assign it to your account ( or request one of the maintainers to assign it to you )
71+
1. **API Layer** - Controllers for assignments, questions, attempts, reports
72+
2. **Service Layer** - Business logic, grading strategies, translation, job processing
73+
3. **Repository Layer** - Data access abstraction
74+
4. **Data Layer** - PostgreSQL with Prisma, caching
75+
5. **LLM Integration** - Facade pattern for AI providers, token tracking, moderation
9976

100-
Please see [docs/CONTRIBUTING.md](./docs/CONTRIBUTING.md) to get started.
77+
### Design Principles
10178

102-
1. Create a feature branch
103-
2. Implement your changes with tests
104-
3. Ensure all tests pass
105-
4. Submit a pull request
79+
- **Repository Pattern** - Centralized data access, improved testability
80+
- **Dependency Injection** - Loose coupling, easier testing
81+
- **Strategy Pattern** - Pluggable grading strategies per question type
82+
- **Rate Limiting** - Bottleneck.js for API throttling
83+
- **Job Queues** - Background processing for long-running tasks
84+
- **Health Monitoring** - System checks and recovery mechanisms
10685

107-
## System Architecture Diagram
86+
<details>
87+
<summary><strong>View Detailed Architecture Diagram</strong></summary>
10888

10989
```mermaid
11090
graph TD
@@ -275,9 +255,6 @@ subgraph "Background Processing"
275255
JSS --> JPQ
276256
end
277257
278-
%% ─────────────── CACHE ───────────────
279-
280-
281258
%% ─────────────── MONITORING ──────────
282259
subgraph "Monitoring System"
283260
direction TB
@@ -286,8 +263,6 @@ subgraph "Monitoring System"
286263
JSS --> Metrics
287264
end
288265
289-
290-
291266
%% ─────────────── COLOUR CLASSES ─────
292267
classDef clientLayer fill:#b3e0ff,stroke:#005b9f,color:#000,font-weight:bold;
293268
classDef apiLayer fill:#c6ffad,stroke:#2a7000,color:#000,font-weight:bold;
@@ -312,11 +287,25 @@ class JPQ,W1,W2,W3 jobLayer
312287
class Cache cacheLayer
313288
class ELK,Metrics,Socket monitoringLayer
314289
class NATS,GHAPI externalLayer
315-
316290
```
317291

292+
</details>
293+
294+
---
295+
296+
## Contributing
297+
298+
We welcome contributions! Here's how to get started:
299+
300+
1. **Read the guidelines** - [CONTRIBUTING.md](./docs/CONTRIBUTING.md)
301+
2. **Pick an issue** - Browse the [project board](https://github.com/orgs/ibm-skills-network/projects/9)
302+
3. **Follow conventions** - Conventional Commits for all PRs and commits
303+
4. **Submit PR** - Include tests and ensure CI passes
304+
305+
All commits and PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/) format (enforced via Husky and CI).
306+
307+
---
308+
318309
## Acknowledgments
319310

320-
- NestJS Team for the excellent framework
321-
- OpenAI for their powerful language models
322-
- Education Technology community for continuous feedback
311+
Built with NestJS, PostgreSQL, Prisma, OpenAI, and the support of the education technology community.

‎apps/api/package.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,8 @@
100100
"form-data": "4.0.4"
101101
},
102102
"devDependencies": {
103+
"@commitlint/cli": "^20.1.0",
104+
"@commitlint/config-conventional": "^20.0.0",
103105
"@ianvs/prettier-plugin-sort-imports": "^4.0.2",
104106
"@nestjs/cli": "10.4.5",
105107
"@nestjs/schematics": "^10.0.0",
@@ -120,7 +122,7 @@
120122
"eslint-config-prettier": "^8.8.0",
121123
"eslint-plugin-prettier": "^4.2.1",
122124
"eslint-plugin-unicorn": "^47.0.0",
123-
"husky": "^8.0.3",
125+
"husky": "^9.1.7",
124126
"jest": "^29.5.0",
125127
"prettier": "^2.8.8",
126128
"prettier-plugin-pkg": "^0.19.0",

‎commitlint.config.js‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
export default {
2+
extends: ["@commitlint/config-conventional"],
3+
rules: {
4+
"header-max-length": [2, "always", 72],
5+
"scope-enum": [
6+
2,
7+
"always",
8+
[
9+
"api",
10+
"web",
11+
"docs",
12+
"deps",
13+
"tests",
14+
"ci",
15+
"build",
16+
"chore",
17+
"feat",
18+
"fix",
19+
"perf",
20+
"refactor",
21+
"revert",
22+
"style",
23+
],
24+
],
25+
},
26+
};

0 commit comments

Comments
 (0)