Opsfolio Documentation

Unified documentation site for all Opsfolio products and services

🌐 Live Documentation

Main Site: https://docs.opsfolio.com

Product Documentation

Spry: docs.opsfolio.com/spry
Surveilr: docs.opsfolio.com/surveilr
QualityFolio: docs.opsfolio.com/qualityfolio
EAA: docs.opsfolio.com/eaa

🏗️ Repository Overview

This is a unified documentation site covering all Opsfolio products. It's built with Next.js, Fumadocs, and Tailwind CSS.

Products Covered

Product	Description	Docs Path
Spry	Operations management & workflow automation	`/spry`
Surveilr	Surveillance & monitoring platform	`/surveilr`
QualityFolio	Quality assurance & testing	`/qualityfolio`
EAA	Enterprise Asset Assessment	`/eaa`

🌟 Features

📚 Comprehensive Documentation - Well-organized documentation with multiple sections
🤖 AI-Powered Search - Ask AI questions powered by Groq
💬 User Feedback System - Collect feedback with JSON storage
🎨 Modern UI - Beautiful, responsive design with dark mode
📱 Mobile Friendly - Fully responsive layout
⚡ Fast Performance - Built with Next.js 16 and Turbopack
🔍 Full-Text Search - Integrated search across all docs
📧 GitHub Integration - Shows last edit time for each page
🎯 Professional Branding - Consistent logo and favicon

🛠️ Tech Stack

Technology	Purpose	Version
Next.js	React framework	16.0.1
Fumadocs	Documentation framework	16.2.4
Tailwind CSS	Styling	4.1.16
TypeScript	Type safety	5.9.3
Groq	AI provider	Latest
AI SDK	AI integration	5.0.104
Lucide React	Icons	0.552.0
Zod	Validation	4.1.13

📁 Project Structure

docs.opsfolio.com/
├── content/
│   └── docs/                         # 📚 All documentation
│       ├── meta.json                 # Root navigation
│       ├── index.mdx                 # Home page
│       ├── getting-started.mdx       # Global getting started
│       ├── spry/                     # Spry product docs
│       │   ├── meta.json
│       │   ├── index.mdx
│       │   ├── getting-started/
│       │   ├── core-concepts/
│       │   ├── reference-guides/
│       │   └── advanced/
│       ├── surveilr/                 # Surveilr product docs
│       ├── qualityfolio/             # QualityFolio product docs
│       └── eaa/                      # EAA product docs
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── chat/                 # 🤖 AI chat endpoint
│   │   │   ├── feedback/             # 👍 Feedback API
│   │   │   └── search/               # 🔍 Search endpoint
│   │   ├── (docs)/                   # Dynamic docs pages
│   │   ├── (home)/                   # Home/landing page
│   │   ├── layout.tsx
│   │   ├── global.css
│   │   └── mdx-components.tsx
│   ├── components/
│   │   ├── feedback.tsx
│   │   ├── search.tsx
│   │   ├── navbar.tsx
│   │   └── ui/
│   ├── lib/
│   │   ├── source.ts                 # Fumadocs config
│   │   ├── layout.shared.tsx
│   │   ├── db.ts
│   │   └── feedback.ts
│   └── mdx-components.tsx
├── db/
│   └── feedback.json                 # Auto-created
├── public/
│   ├── favicon.ico
│   ├── logo.png
│   ├── logo.svg
│   └── robots.txt
├── .env.sample                       # Environment template
├── source.config.ts                  # MDX configuration
├── next.config.mjs
├── tailwind.config.ts
├── package.json
└── README.md

Key Directories:

content/docs/ = All documentation content
src/app/ = Next.js pages and layouts
src/components/ = React components
src/lib/ = Utility functions and configs
public/ = Static files (images, icons)

🚀 Quick Start

Prerequisites

Node.js 18 or higher
npm 10 or higher
Git
Groq API Key (Get free key)

Installation

Clone the repository

   git clone https://github.com/opsfolio/docs.opsfolio.com.git
   cd docs.opsfolio.com

Install dependencies

   npm install

Set up environment variables

   cp .env.sample .env.local

Add your API key to .env.local:

   # Required: Get free key at https://console.groq.com/keys
   GROQ_API_KEY=gsk_your_actual_key_here
   
   # Optional: GitHub integration
   GITHUB_TOKEN=ghp_your_token_here
   NEXT_PUBLIC_GITHUB_OWNER=opsfolio
   NEXT_PUBLIC_GITHUB_REPO=docs.opsfolio.com
   NEXT_PUBLIC_GITHUB_DOCS_PATH=content/docs

Start development server

   npm run dev

Open in browser

Navigate to http://localhost:3000

🌍 Environment Variables

Required

Variable	Description	Get Value
`GROQ_API_KEY`	Groq AI API key for search	console.groq.com/keys

Optional

Variable	Description	Default
`GITHUB_TOKEN`	GitHub token for last edit time	(not set)
`NEXT_PUBLIC_GITHUB_OWNER`	GitHub repository owner	opsfolio
`NEXT_PUBLIC_GITHUB_REPO`	GitHub repository name	docs.opsfolio.com
`NEXT_PUBLIC_GITHUB_DOCS_PATH`	Path to docs in repo	content/docs

📖 Documentation Guide

Adding New Documentation

Create a new .mdx file in content/docs/ subdirectory

   touch content/docs/spry/section/new-page.mdx

Add frontmatter:

   ---
   title: "Your Page Title"
   description: "Brief description for SEO"
   icon: "FileText"
   ---

   # Your Content Here

   Content using MDX syntax...

Update meta.json to include your page in navigation:

   {
     "title": "Section Name",
     "pages": ["existing-page", "new-page"]
   }

Preview changes:

   npm run dev

Documentation Structure

Each product follows this structure:

product-name/
├── meta.json              # Navigation config
├── index.mdx             # Product overview
├── getting-started/      # Getting started guides
├── core-concepts/        # Fundamental concepts
├── reference-guides/     # API/CLI references
└── advanced/             # Advanced topics

Writing Guidelines

Clear & Concise: Use simple language
Action-Oriented: Start with verbs
Code Examples: Include working snippets
Consistent Terminology: Use same terms across products
Visual Aids: Add diagrams/screenshots where helpful

💬 Features Guide

🤖 AI Search

Users can access AI search by:

Clicking the Ask AI button (bottom-right)
Using keyboard shortcut: Cmd+/ (Mac) or Ctrl+/ (Windows/Linux)

Capabilities:

Natural language questions
AI-powered answers with relevant links
Retry/regenerate responses
Full conversation history
Powered by Groq (Llama 3.3 70B)

👍 Feedback System

Users can provide feedback on pages:

Thumbs Up - Mark page as helpful
Thumbs Down - Mark page as unhelpful
Optional Message - Add detailed feedback
Automatic Metadata - Captures user agent, timezone, platform

Storage: Saved to db/feedback.json (auto-created)

🔍 Search

Built-in full-text search:

Fast and responsive
Shows relevant results
Easy navigation

🔧 Configuration

Site Settings

Configure in src/lib/layout.shared.tsx:

Logo: public/logo.png
Title: "Opsfolio Documentation"
Navigation options

Styling

Tailwind CSS 4: Main styling framework
PostCSS: Advanced styling
Dark Mode: Built-in support

📊 Database

Feedback Storage

Stored in db/feedback.json:

[
  {
    "id": 1,
    "url": "/spry/getting-started",
    "opinion": "good",
    "message": "Very helpful!",
    "session_id": "1701520800000-abc123",
    "metadata": "{\"userAgent\":\"...\"}",
    "created_at": "2024-12-02T10:00:00Z"
  }
]

🌐 API Routes

POST `/api/feedback`

Save user feedback

Request:

{
  "type": "good" | "bad",
  "page": "/docs/page-path",
  "timestamp": "2024-12-02T10:00:00Z"
}

Response: { "success": true }

POST `/api/chat`

AI-powered documentation Q&A

Uses Groq API (Llama 3.3 70B)
Context-aware responses
Error handling

GET `/api/search`

Full-text search

Query parameter: q
Returns relevant pages

📦 Available Scripts

# Development
npm run dev              # Start dev server (:3000)
npm run build            # Build for production
npm start                # Start production server

# Code Quality
npm run lint             # Run ESLint
npm run types:check      # TypeScript validation

🚢 Deployment

Vercel (Recommended)

Push code to GitHub
Import at Vercel Dashboard
Add environment variables:
- GROQ_API_KEY
- GITHUB_TOKEN (optional)
Deploy

Docker

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

Self-Hosted

npm run build
# Deploy .next/, db/, public/, package.json
npm install --prod
npm start

🐛 Troubleshooting

Issue	Solution
AI Search not working	Verify `GROQ_API_KEY` in `.env.local`
Feedback not saving	Check `db/` permissions
GitHub last edit missing	Add `GITHUB_TOKEN` to `.env.local`
Build fails	Run `rm -rf .next && npm install`
TypeScript errors	Run `npm run types:check`

🤝 Contributing

We welcome contributions!

Fork the repository
Create feature branch (git checkout -b docs/feature)
Make changes
Test locally (npm run dev)
Commit with clear messages
Push and create Pull Request

Guidelines

Follow existing structure
Use consistent terminology
Include code examples
Test all links
Update meta.json files

📞 Support

🐛 Issues: GitHub Issues

🔗 Resources

🙏 Acknowledgments

Built with Fumadocs
Powered by Next.js
Styled with Tailwind CSS
AI by Groq

📚 Additional Documentation

For detailed guidelines, see:

GETTING-STARTED.md - Comprehensive getting started guide

Name		Name	Last commit message	Last commit date
Latest commit History 448 Commits
.github/workflows		.github/workflows
content/docs		content/docs
db		db
public		public
src		src
.env.sample		.env.sample
.gitignore		.gitignore
README.md		README.md
cli.json		cli.json
eslint.config.mjs		eslint.config.mjs
getting-started.md		getting-started.md
next.config.mjs		next.config.mjs
package.json		package.json
pnpm-workspace.yaml		pnpm-workspace.yaml
postcss.config.mjs		postcss.config.mjs
source.config.ts		source.config.ts
tsconfig.json		tsconfig.json

Abin-Sec/docs.opsfolio.com

Folders and files

Latest commit

History

Repository files navigation