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.
This commit is contained in:
shancheas
+37
-423
@@ -1,443 +1,57 @@
|
|||||||
---
|
---
|
||||||
name: doc-updater
|
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
|
tools: Read, Write, Edit, Bash, Grep, Glob
|
||||||
model: opus
|
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
|
| Kind | Location | Audience |
|
||||||
2. **Documentation Updates** - Refresh READMEs and guides from code
|
| --- | --- | --- |
|
||||||
3. **AST Analysis** - Use TypeScript compiler API to understand structure
|
| Technical | `docs/` + `mkdocs.yml` (this repo) | Developers / engineers |
|
||||||
4. **Dependency Mapping** - Track imports/exports across modules
|
| User | sibling `trackgo-fe/apps/docs-dev/` | Customers / operators |
|
||||||
5. **Documentation Quality** - Ensure docs match reality
|
|
||||||
|
|
||||||
## 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
|
Technical coverage under `docs/`:
|
||||||
- **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
|
|
||||||
|
|
||||||
### Analysis Commands
|
```text
|
||||||
```bash
|
docs/
|
||||||
# Analyze TypeScript project structure
|
backend/ # NestJS API — this repo
|
||||||
npx ts-morph
|
frontend-web/ # trackgo-fe/apps/web
|
||||||
|
frontend-landing/ # trackgo-fe/apps/landing
|
||||||
# Generate dependency graph
|
mobile/ # trackgo_mobile
|
||||||
npx madge --image graph.svg src/
|
api.md # HTTP API reference (keep)
|
||||||
|
report-*.md # report docs (keep)
|
||||||
# Extract JSDoc comments
|
|
||||||
npx jsdoc2md src/**/*.ts
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Codemap Generation Workflow
|
## Source of truth
|
||||||
|
|
||||||
### 1. Repository Structure Analysis
|
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`
|
||||||
a) Identify all workspaces/packages
|
3. Sibling `trackgo_mobile`: `lib/config/router.dart`, `lib/ui/features/`, `pubspec.yaml`
|
||||||
b) Map directory structure
|
|
||||||
c) Find entry points (apps/*, packages/*, services/*)
|
|
||||||
d) Detect framework patterns (NestJS, Node.js, etc.)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Module Analysis
|
If a product brief disagrees with code, follow the code or label **Coming soon**. No emoji. Diagrams: PlantUML fenced blocks, not Mermaid.
|
||||||
```
|
|
||||||
For each module:
|
|
||||||
- Extract exports (public API)
|
|
||||||
- Map imports (dependencies)
|
|
||||||
- Identify routes (API routes, pages)
|
|
||||||
- Find database models (Drizzle schema)
|
|
||||||
- Locate queue/worker modules
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Generate Codemaps
|
## Workflow
|
||||||
```
|
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. Codemap Format
|
1. Discover modules from `src/app.module.ts` (Auth, Users, Privileges, Configuration, Sales, Field, Reports)
|
||||||
```markdown
|
2. Cross-read sibling FE/mobile for frontend-web, frontend-landing, and mobile sections
|
||||||
# [Area] Codemap
|
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
|
## Quality
|
||||||
**Entry Points:** list of main files
|
|
||||||
|
|
||||||
## Architecture
|
- Every path mentioned must exist in the relevant repo
|
||||||
|
- Commands must match each repo's package manager scripts
|
||||||
[ASCII diagram of component relationships]
|
- 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
|
||||||
## Key Modules
|
- Do not invent features or endpoints
|
||||||
|
|
||||||
| 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).
|
|
||||||
|
|||||||
@@ -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`).
|
||||||
@@ -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
|
||||||
|
```
|
||||||
@@ -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
|
||||||
|
```
|
||||||
@@ -0,0 +1,8 @@
|
|||||||
|
site_name: 'Concourse CI'
|
||||||
|
|
||||||
|
nav:
|
||||||
|
- Home: index.md
|
||||||
|
- Android APK Build: android-apk-build.md
|
||||||
|
|
||||||
|
plugins:
|
||||||
|
- techdocs-core
|
||||||
Reference in New Issue
Block a user