From a6a06ae1dee273aa15e6897628c26de0709bd9c5 Mon Sep 17 00:00:00 2001 From: shancheas Date: Fri, 4 Sep 2026 15:54:39 +0700 Subject: [PATCH] Add MkDocs configuration and documentation rules for TrackGo - 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. --- .cursor/agents/doc-updater.md | 460 +++---------------------------- .cursor/rules/documentation.mdc | 24 ++ .cursor/rules/technical-docs.mdc | 79 ++++++ docs/readme.md | 8 + mkdocs.yml | 8 + 5 files changed, 156 insertions(+), 423 deletions(-) create mode 100644 .cursor/rules/documentation.mdc create mode 100644 .cursor/rules/technical-docs.mdc create mode 100644 docs/readme.md create mode 100644 mkdocs.yml diff --git a/.cursor/agents/doc-updater.md b/.cursor/agents/doc-updater.md index 8d9199e..300777f 100644 --- a/.cursor/agents/doc-updater.md +++ b/.cursor/agents/doc-updater.md @@ -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//` 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 diff --git a/.cursor/rules/documentation.mdc b/.cursor/rules/documentation.mdc new file mode 100644 index 0000000..eee9453 --- /dev/null +++ b/.cursor/rules/documentation.mdc @@ -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`). diff --git a/.cursor/rules/technical-docs.mdc b/.cursor/rules/technical-docs.mdc new file mode 100644 index 0000000..7f83650 --- /dev/null +++ b/.cursor/rules/technical-docs.mdc @@ -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 +``` diff --git a/docs/readme.md b/docs/readme.md new file mode 100644 index 0000000..ab22996 --- /dev/null +++ b/docs/readme.md @@ -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 +``` diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..000d4c3 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,8 @@ +site_name: 'Concourse CI' + +nav: + - Home: index.md + - Android APK Build: android-apk-build.md + +plugins: + - techdocs-core