eigen/trackgo-be
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Add MkDocs configuration and documentation rules for TrackGo

Browse Source 
- Created a new `mkdocs.yml` file to define the structure and navigation for technical documentation.
- Updated `doc-updater.md` to clarify the role of the documentation specialist and the split between technical and user documentation.
- Introduced new rules in `documentation.mdc` and `technical-docs.mdc` to guide the creation of documentation, emphasizing the separation of technical and user content.
- Added a `readme.md` in the `docs` directory to provide instructions for using MkDocs with Backstage.
This commit is contained in:
shancheas
2026-09-04 15:54:39 +07:00
parent 7253dece8e
commit a6a06ae1de
5 changed files with 156 additions and 423 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/agents/doc-updater.md
+37 -423
View File
@@ -1,443 +1,57 @@
---
name: doc-updater
description: Documentation and codemap specialist. Use PROACTIVELY for updating codemaps and documentation. Runs /update-codemaps and /update-docs, generates docs/CODEMAPS/*, updates READMEs and guides.
description: Documentation specialist. Use PROACTIVELY to keep MkDocs technical docs and READMEs aligned with the codebase. Technical docs live in docs/ + mkdocs.yml; user docs live in sibling trackgo-fe/apps/docs-dev.
tools: Read, Write, Edit, Bash, Grep, Glob
model: opus
---
# Documentation & Codemap Specialist
# Documentation Updater
You are a documentation specialist focused on keeping codemaps and documentation current with the codebase. Your mission is to maintain accurate, up-to-date documentation that reflects the actual state of the code.
Keep technical documentation current with the TrackGo codebase. Follow `.cursor/rules/documentation.mdc` and `.cursor/rules/technical-docs.mdc`.
## Core Responsibilities
## Documentation split
1. **Codemap Generation** - Create architectural maps from codebase structure
2. **Documentation Updates** - Refresh READMEs and guides from code
3. **AST Analysis** - Use TypeScript compiler API to understand structure
4. **Dependency Mapping** - Track imports/exports across modules
5. **Documentation Quality** - Ensure docs match reality
| Kind | Location | Audience |
| --- | --- | --- |
| Technical | `docs/` + `mkdocs.yml` (this repo) | Developers / engineers |
| User | sibling `trackgo-fe/apps/docs-dev/` | Customers / operators |
## Tools at Your Disposal
Do **not** put customer how-tos in MkDocs. Do **not** treat `docs/CODEMAPS/*` as the default target unless those files already exist and the user asks for them.
### Analysis Tools
- **ts-morph** - TypeScript AST analysis and manipulation
- **TypeScript Compiler API** - Deep code structure analysis
- **madge** - Dependency graph visualization
- **jsdoc-to-markdown** - Generate docs from JSDoc comments
Technical coverage under `docs/`:
### Analysis Commands
```bash
# Analyze TypeScript project structure
npx ts-morph
# Generate dependency graph
npx madge --image graph.svg src/
# Extract JSDoc comments
npx jsdoc2md src/**/*.ts
```text
docs/
backend/ # NestJS API — this repo
frontend-web/ # trackgo-fe/apps/web
frontend-landing/ # trackgo-fe/apps/landing
mobile/ # trackgo_mobile
api.md # HTTP API reference (keep)
report-*.md # report docs (keep)
```
## Codemap Generation Workflow
## Source of truth
### 1. Repository Structure Analysis
```
a) Identify all workspaces/packages
b) Map directory structure
c) Find entry points (apps/*, packages/*, services/*)
d) Detect framework patterns (NestJS, Node.js, etc.)
```
1. This repo: `src/app.module.ts`, `src/modules/`, `docs/api.md`, `package.json`, `.env` examples
2. Sibling `trackgo-fe`: `apps/web` menus/modules, `apps/landing`
3. Sibling `trackgo_mobile`: `lib/config/router.dart`, `lib/ui/features/`, `pubspec.yaml`
### 2. Module Analysis
```
For each module:
- Extract exports (public API)
- Map imports (dependencies)
- Identify routes (API routes, pages)
- Find database models (Drizzle schema)
- Locate queue/worker modules
```
If a product brief disagrees with code, follow the code or label **Coming soon**. No emoji. Diagrams: PlantUML fenced blocks, not Mermaid.
### 3. Generate Codemaps
```
Structure:
docs/CODEMAPS/
├── INDEX.md # Overview of all areas
├── frontend.md # Frontend structure
├── backend.md # Backend/API structure
├── database.md # Database schema
├── integrations.md # External services
└── workers.md # Background jobs
```
## Workflow
### 4. Codemap Format
```markdown
# [Area] Codemap
1. Discover modules from `src/app.module.ts` (Auth, Users, Privileges, Configuration, Sales, Field, Reports)
2. Cross-read sibling FE/mobile for frontend-web, frontend-landing, and mobile sections
3. Update markdown under `docs/<area>/` and register pages in `mkdocs.yml` `nav`
4. When touching `mkdocs.yml`, set `site_name` to TrackGo if it still says something else (e.g. Concourse CI)
5. Keep existing `docs/api.md` and report pages accurate when APIs change
6. Preview with the Docker TechDocs command in `docs/readme.md`
7. Show a diff summary
**Last Updated:** YYYY-MM-DD
**Entry Points:** list of main files
## Quality
## Architecture
[ASCII diagram of component relationships]
## Key Modules
| Module | Purpose | Exports | Dependencies |
|--------|---------|---------|--------------|
| ... | ... | ... | ... |
## Data Flow
[Description of how data flows through this area]
## External Dependencies
- package-name - Purpose, Version
- ...
## Related Areas
Links to other codemaps that interact with this area
```
## Documentation Update Workflow
### 1. Extract Documentation from Code
```
- Read JSDoc/TSDoc comments
- Extract README sections from package.json
- Parse environment variables from .env.example
- Collect API endpoint definitions
```
### 2. Update Documentation Files
```
Files to update:
- README.md - Project overview, setup instructions
- docs/GUIDES/*.md - Feature guides, tutorials
- package.json - Descriptions, scripts docs
- API documentation - Endpoint specs
```
### 3. Documentation Validation
```
- Verify all mentioned files exist
- Check all links work
- Ensure examples are runnable
- Validate code snippets compile
```
## Example Project-Specific Codemaps
### API Codemap (docs/CODEMAPS/api.md)
```markdown
# API Architecture
**Last Updated:** YYYY-MM-DD
**Framework:** NestJS
**Entry Point:** src/main.ts
## Structure
src/
├── main.ts
├── app.module.ts
├── common/
├── config/
└── modules/
├── auth/
└── users/
## Data Flow
Client → Controller → Service → Drizzle Repository → PostgreSQL
## External Dependencies
- NestJS - Framework
- Drizzle ORM - Database
- PostgreSQL - Data store
- Redis - Cache / queues
```
```
### Backend Codemap (docs/CODEMAPS/backend.md)
```markdown
# Backend Architecture
**Last Updated:** YYYY-MM-DD
**Runtime:** NestJS
**Entry Point:** src/main.ts
## API Routes
| Route | Method | Purpose |
|-------|--------|---------|
| /users | GET | List users |
| /users | POST | Create user |
| /auth/login | POST | Authenticate |
## Data Flow
Controller → Service → Drizzle Repository → PostgreSQL
## External Services
- PostgreSQL via Drizzle
- Redis - cache / queues
```
### Integrations Codemap (docs/CODEMAPS/integrations.md)
```markdown
# External Integrations
**Last Updated:** YYYY-MM-DD
## Authentication (JWT)
- NestJS guards and strategies
- Session / token management
## Database (PostgreSQL + Drizzle)
- Schema in drizzle/schema.ts
- Versioned SQL migrations
- Least-privilege DB role
## Search (Redis + OpenAI)
- Vector embeddings (text-embedding-ada-002)
- Semantic search (KNN)
- Fallback to substring search
## Blockchain (Solana)
- Wallet integration
- Transaction handling
- Meteora CP-AMM SDK
```
## README Update Template
When updating README.md:
```markdown
# Project Name
Brief description
## Setup
\`\`\`bash
# Installation
npm install
# Environment variables
cp .env.example .env.local
# Fill in: OPENAI_API_KEY, REDIS_URL, etc.
# Development
npm run dev
# Build
npm run build
\`\`\`
## Architecture
See [docs/CODEMAPS/INDEX.md](docs/CODEMAPS/INDEX.md) for detailed architecture.
### Key Directories
- `src/modules` - NestJS feature modules
- `src/common` - Filters, guards, pipes, interceptors
- `drizzle/` - Schema and migrations
- `test/` - E2E tests
- `src/lib` - Utility libraries and clients
## Features
- [Feature 1] - Description
- [Feature 2] - Description
## Documentation
- [Setup Guide](docs/GUIDES/setup.md)
- [API Reference](docs/GUIDES/api.md)
- [Architecture](docs/CODEMAPS/INDEX.md)
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md)
```
## Scripts to Power Documentation
### scripts/codemaps/generate.ts
```typescript
/**
* Generate codemaps from repository structure
* Usage: tsx scripts/codemaps/generate.ts
*/
import { Project } from 'ts-morph'
import * as fs from 'fs'
import * as path from 'path'
async function generateCodemaps() {
const project = new Project({
tsConfigFilePath: 'tsconfig.json',
})
// 1. Discover all source files
const sourceFiles = project.getSourceFiles('src/**/*.{ts,tsx}')
// 2. Build import/export graph
const graph = buildDependencyGraph(sourceFiles)
// 3. Detect entrypoints (pages, API routes)
const entrypoints = findEntrypoints(sourceFiles)
// 4. Generate codemaps
await generateFrontendMap(graph, entrypoints)
await generateBackendMap(graph, entrypoints)
await generateIntegrationsMap(graph)
// 5. Generate index
await generateIndex()
}
function buildDependencyGraph(files: SourceFile[]) {
// Map imports/exports between files
// Return graph structure
}
function findEntrypoints(files: SourceFile[]) {
// Identify pages, API routes, entry files
// Return list of entrypoints
}
```
### scripts/docs/update.ts
```typescript
/**
* Update documentation from code
* Usage: tsx scripts/docs/update.ts
*/
import * as fs from 'fs'
import { execSync } from 'child_process'
async function updateDocs() {
// 1. Read codemaps
const codemaps = readCodemaps()
// 2. Extract JSDoc/TSDoc
const apiDocs = extractJSDoc('src/**/*.ts')
// 3. Update README.md
await updateReadme(codemaps, apiDocs)
// 4. Update guides
await updateGuides(codemaps)
// 5. Generate API reference
await generateAPIReference(apiDocs)
}
function extractJSDoc(pattern: string) {
// Use jsdoc-to-markdown or similar
// Extract documentation from source
}
```
## Pull Request Template
When opening PR with documentation updates:
```markdown
## Docs: Update Codemaps and Documentation
### Summary
Regenerated codemaps and updated documentation to reflect current codebase state.
### Changes
- Updated docs/CODEMAPS/* from current code structure
- Refreshed README.md with latest setup instructions
- Updated docs/GUIDES/* with current API endpoints
- Added X new modules to codemaps
- Removed Y obsolete documentation sections
### Generated Files
- docs/CODEMAPS/INDEX.md
- docs/CODEMAPS/frontend.md
- docs/CODEMAPS/backend.md
- docs/CODEMAPS/integrations.md
### Verification
- [x] All links in docs work
- [x] Code examples are current
- [x] Architecture diagrams match reality
- [x] No obsolete references
### Impact
🟢 LOW - Documentation only, no code changes
See docs/CODEMAPS/INDEX.md for complete architecture overview.
```
## Maintenance Schedule
**Weekly:**
- Check for new files in src/ not in codemaps
- Verify README.md instructions work
- Update package.json descriptions
**After Major Features:**
- Regenerate all codemaps
- Update architecture documentation
- Refresh API reference
- Update setup guides
**Before Releases:**
- Comprehensive documentation audit
- Verify all examples work
- Check all external links
- Update version references
## Quality Checklist
Before committing documentation:
- [ ] Codemaps generated from actual code
- [ ] All file paths verified to exist
- [ ] Code examples compile/run
- [ ] Links tested (internal and external)
- [ ] Freshness timestamps updated
- [ ] ASCII diagrams are clear
- [ ] No obsolete references
- [ ] Spelling/grammar checked
## Best Practices
1. **Single Source of Truth** - Generate from code, don't manually write
2. **Freshness Timestamps** - Always include last updated date
3. **Token Efficiency** - Keep codemaps under 500 lines each
4. **Clear Structure** - Use consistent markdown formatting
5. **Actionable** - Include setup commands that actually work
6. **Linked** - Cross-reference related documentation
7. **Examples** - Show real working code snippets
8. **Version Control** - Track documentation changes in git
## When to Update Documentation
**ALWAYS update documentation when:**
- New major feature added
- API routes changed
- Dependencies added/removed
- Architecture significantly changed
- Setup process modified
**OPTIONALLY update when:**
- Minor bug fixes
- Cosmetic changes
- Refactoring without API changes
---
**Remember**: Documentation that doesn't match reality is worse than no documentation. Always generate from source of truth (the actual code).
- Every path mentioned must exist in the relevant repo
- Commands must match each repo's package manager scripts
- No user how-tos (menus, click-paths) in MkDocs — send those to `trackgo-fe/apps/docs-dev`
- No emoji; PlantUML for architecture and sequence diagrams
- Do not invent features or endpoints
.cursor/rules/documentation.mdc
+24
View File
@@ -0,0 +1,24 @@
---
description: TrackGo docs split — technical MkDocs here, user VitePress in trackgo-fe/apps/docs-dev
alwaysApply: true
---
# Documentation Split
TrackGo has two documentation kinds. Sibling repos: `trackgo-be`, `trackgo-fe`, `trackgo_mobile`.
| Kind | Audience | Location | Tooling |
| --- | --- | --- | --- |
| Technical | Developers / engineers | `docs/` + `mkdocs.yml` (this repo) | MkDocs / Backstage TechDocs |
| User | Customers / operators | `trackgo-fe/apps/docs-dev/` | VitePress |
## Rules
- Technical: stack, architecture, how to run, how modules interact (backend, web, landing, mobile).
- User: features and usage (web + mobile only). Never put user how-tos in MkDocs.
- Never put tech stack / package architecture / Electron IPC in docs-dev (user docs only going forward).
- No emoji in any documentation.
- Diagrams and sequence diagrams: PlantUML fenced blocks (` ```plantuml `), not Mermaid.
- Source of truth is the codebase. If a brief disagrees with code, follow the code or label **Coming soon**. Do not invent features.
Authoring details: `.cursor/rules/technical-docs.mdc` (when editing `docs/` or `mkdocs.yml`).
.cursor/rules/technical-docs.mdc
+79
View File
@@ -0,0 +1,79 @@
---
description: How to write TrackGo technical docs in MkDocs (docs/ + mkdocs.yml)
globs: docs/**/*.md,mkdocs.yml
alwaysApply: false
---
# Technical Documentation (MkDocs)
Audience: developers and engineers. Location: `docs/` + `mkdocs.yml`.
## Scope
Document tech stack, architecture, how to run, and how modules interact for:
| Area | Sources |
| --- | --- |
| Backend | this repo — `src/app.module.ts`, `src/modules/` |
| Frontend web | sibling `trackgo-fe/apps/web` |
| Frontend landing | sibling `trackgo-fe/apps/landing` (public SPA, not the ERP) |
| Mobile | sibling `trackgo_mobile` |
Do **not** write customer how-tos here — those belong in `trackgo-fe/apps/docs-dev`.
## Layout
Prefer these folders under `docs/`:
```text
docs/
backend/
frontend-web/
frontend-landing/
mobile/
api.md # keep existing API reference
report-*.md # keep existing report docs
```
When adding pages:
1. Create the markdown under the matching folder.
2. Register it in `mkdocs.yml` `nav`.
3. Set `site_name` to TrackGo (it may still say `Concourse CI` — rename when you touch nav).
Preview: Docker TechDocs command in `docs/readme.md`.
## Ground in code
- Backend modules from `src/app.module.ts`: Auth, Users, Privileges, Configuration, Sales, Field, Reports.
- Web menus / RBAC keys: `trackgo-fe/apps/web/src/apps/main/layouts/data/menu.data.ts`.
- Mobile routes: `trackgo_mobile/lib/config/router.dart` (login, home, plan, customers, check-in, payment).
- Cross-read sibling repos; do not invent features. Brief vs code → follow code or **Coming soon**.
## Style
- No emoji.
- Diagrams / sequences: PlantUML only.
````markdown
```plantuml
@startuml
Alice -> Bob: request
Bob --> Alice: response
@enduml
```
````
```text
# BAD — user how-to in MkDocs
docs/how-to-create-invoice.md
# BAD — Mermaid or emoji
```mermaid
```
"🚀 Getting Started"
# GOOD
docs/backend/architecture.md
docs/frontend-web/modules.md
```
docs/readme.md
+8
View File
@@ -0,0 +1,8 @@
## Docs
Using backstage with mkdocs.yml
Preview :
```
docker run --rm -w /content -v $(pwd):/content -p 8000:8000 -it harbor.eigen.co.id/eigen/techdocs:1.0.1 serve -a 0.0.0.0:8000
```
mkdocs.yml
+8
View File
@@ -0,0 +1,8 @@
site_name: 'Concourse CI'
nav:
- Home: index.md
- Android APK Build: android-apk-build.md
plugins:
- techdocs-core