{"id":39352064,"url":"https://github.com/amoskyalo/daraja-docs","last_synced_at":"2026-01-18T02:32:02.786Z","repository":{"id":319642736,"uuid":"1039714035","full_name":"amoskyalo/daraja-docs","owner":"amoskyalo","description":"A modern, comprehensive documentation platform for Safaricom's Daraja API - M-Pesa integration made simple.","archived":false,"fork":false,"pushed_at":"2025-12-06T10:24:56.000Z","size":2503,"stargazers_count":39,"open_issues_count":0,"forks_count":12,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2025-12-08T14:42:44.284Z","etag":null,"topics":["daraja","daraja-api","daraja-mpesa","graphql","monorepo","nextjs","turborepo"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amoskyalo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-17T20:36:31.000Z","updated_at":"2025-12-07T07:35:09.000Z","dependencies_parsed_at":"2025-10-26T21:08:02.637Z","dependency_job_id":null,"html_url":"https://github.com/amoskyalo/daraja-docs","commit_stats":null,"previous_names":["amoskyalo/daraja-docs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/amoskyalo/daraja-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amoskyalo%2Fdaraja-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amoskyalo%2Fdaraja-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amoskyalo%2Fdaraja-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amoskyalo%2Fdaraja-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amoskyalo","download_url":"https://codeload.github.com/amoskyalo/daraja-docs/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amoskyalo%2Fdaraja-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28526572,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["daraja","daraja-api","daraja-mpesa","graphql","monorepo","nextjs","turborepo"],"created_at":"2026-01-18T02:32:02.672Z","updated_at":"2026-01-18T02:32:02.753Z","avatar_url":"https://github.com/amoskyalo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Daraja API Documentation Platform\n\nA comprehensive documentation platform for Safaricom's Daraja API (M-Pesa Integration). This project provides interactive documentation, API playground, and AI-powered developer assistance.\n\n## Overview\n\nThe platform consists of three main applications managed as a [Turborepo](https://turbo.build/repo/docs) monorepo:\n\n- **daraja-docs-platform** — Next.js documentation website with AI assistant and interactive features\n- **daraja-graphql-server** — [Apollo Server](https://www.apollographql.com/docs/apollo-server/) providing unified API access\n- **mpesa-sdk-node** — TypeScript SDK for M-Pesa API integration\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 20.x or higher\n- pnpm 9.0.0\n\nInstall pnpm if you don't have it:\n\n```bash\nnpm install -g pnpm@9.0.0\n```\n\n### Installation\n\nClone the repository and install dependencies:\n\n```bash\ngit clone https://github.com/amoskyalo/daraja-docs.git\ncd daraja-docs\npnpm install\n```\n\n### Development\n\nStart all applications:\n\n```bash\npnpm dev\n```\n\nThe frontend runs at `http://localhost:3000` and the GraphQL server at `http://localhost:4000`.\n\nTo run individual applications:\n\n```bash\n# Frontend only\npnpm --filter daraja-docs-platform dev\n\n# Backend only\npnpm --filter daraja-graphql-server dev\n\n# SDK\npnpm --filter mpesa-sdk-node dev\n```\n\n## Configuration\n\n### Frontend Environment Variables\n\nCreate `apps/daraja-docs-platform/.env.local`:\n\n```env\nNEXT_PUBLIC_GRAPHQL_ENDPOINT=http://localhost:4000/graphql\nANTHROPIC_API_KEY=\u003cyour-anthropic-api-key\u003e\nSUPERMEMORY_API_KEY=\u003cyour-supermemory-api-key\u003e\nNEXT_PUBLIC_ALGOLIA_APP_ID=\u003cyour-algolia-app-id\u003e\nNEXT_PUBLIC_ALGOLIA_API_KEY=\u003cyour-algolia-search-key\u003e\n```\n\n**Where to get API keys:**\n- **Anthropic API Key** — Create an account at [console.anthropic.com](https://console.anthropic.com) and generate an API key\n- **Supermemory API Key** — Sign up at [supermemory.ai](https://supermemory.ai) to get an API key for documentation indexing\n- **Algolia Keys** — Sign up at [algolia.com](https://www.algolia.com), create an application, and get your App ID and Search-Only API Key from the dashboard\n\n### Backend Environment Variables\n\nCreate `apps/daraja-graphql-server/.env`:\n\n```env\nPORT=4000\nBASE_URL=\u003cbackend-base-url\u003e\nGITHUB_BASE_URL=https://api.github.com\nGITHUB_API_KEY=\u003cyour-github-personal-access-token\u003e\nHASHNODE_APIS_BASE_URL=https://gql.hashnode.com\nDEVTO_APIS_BASE_URL=https://dev.to/api\n```\n\n**Where to get API keys:**\n- **GitHub Token** — Generate a personal access token at [github.com/settings/tokens](https://github.com/settings/tokens) with `repo` and `read:org` scopes\n- **Hashnode/Dev.to URLs** — These are public API endpoints and work without authentication for read operations\n\nThe application will run without these variables, but certain features will be unavailable.\n\n## Project Structure\n\n```\napps/\n├── daraja-docs-platform/    # Next.js frontend application\n│   ├── src/\n│   │   ├── app/             # App Router pages and layouts\n│   │   ├── features/        # Feature modules\n│   │   ├── shared/          # Shared components and utilities\n│   │   └── config/          # Configuration files\n│   └── package.json\n├── daraja-graphql-server/   # Apollo Server backend\n│   ├── src/\n│   │   ├── typeDefs/        # GraphQL type definitions\n│   │   ├── resolvers/       # GraphQL resolvers\n│   │   └── datasources.ts   # Data source implementations\n│   └── package.json\n└── mpesa-sdk-node/          # TypeScript SDK\n    ├── src/\n    └── package.json\n```\n\n## Technology Stack\n\n### Frontend\n- Next.js 15 with React 19\n- Material-UI (MUI) v7\n- [Apollo Client](https://www.apollographql.com/docs/react/)\n- [TanStack Query](https://tanstack.com/query/latest)\n- MDX for documentation\n- Anthropic SDK for AI features\n- [Algolia](https://www.algolia.com/doc/) for search\n\n### Backend\n- Express 5\n- [Apollo Server](https://www.apollographql.com/docs/apollo-server/) 5\n- TypeScript\n- RESTful data sources\n\n### Infrastructure\n- [Turborepo](https://turbo.build/repo/docs) for monorepo management\n- pnpm workspaces\n- Netlify deployment (frontend)\n\n## Features\n\n### AI Documentation Assistant\n\nThe platform integrates Claude AI to provide context-aware assistance for the Daraja API. Documentation content is indexed using [Supermemory](https://supermemory.ai), enabling the assistant to retrieve relevant context when answering questions. The system processes MDX files, extracts content, and builds a searchable knowledge base that Claude references during conversations.\n\nWhen a user asks a question, the system:\n1. Queries the indexed documentation for relevant sections\n2. Passes the context to Claude via the Anthropic SDK\n3. Returns responses that reference specific documentation\n\nThis enables accurate answers to integration questions like callback handling, authentication flows, and API error troubleshooting.\n\nImplementation: `apps/daraja-docs-platform/src/app/api/ask-docs/route.ts` and `apps/daraja-docs-platform/src/app/api/index-docs/route.ts`\n\n### Interactive API Playground\n\nThe playground provides a browser-based interface for testing Daraja API endpoints. It connects to the GraphQL server, which proxies requests to the actual API while handling authentication. Users can select endpoints, configure parameters through form inputs, and view formatted responses including status codes and response bodies.\n\nThe playground uses the same [GraphQL](https://graphql.org/learn/) layer that powers the documentation site, ensuring consistent API behavior across features. Request history and response caching are handled through Apollo Client.\n\nLocation: `apps/daraja-docs-platform/src/features/playground/`\n\n### Code Generation\n\nCode snippets are generated using Postman's code generator library. The system converts API endpoint configurations into executable code for multiple languages and frameworks:\n- Node.js (Axios, Fetch, Request)\n- Python (Requests, http.client)\n- cURL\n- PHP, Ruby, Java, and others\n\nThe generator takes endpoint definitions including headers, authentication, and request bodies, then produces production-ready code with proper error handling and configuration.\n\nImplementation: `apps/daraja-docs-platform/src/app/api/request-snippet-generator/route.ts`\n\n### MDX Documentation\n\nDocumentation uses MDX (Markdown + JSX), processed server-side with `next-mdx-remote`. This enables:\n\n- React component embedding in markdown content\n- Dynamic content generation\n- Consistent styling through custom component mappings\n- Syntax highlighting via rehype-prism-plus\n- Automatic table of contents generation from heading structure\n\nFrontmatter metadata is extracted with gray-matter and used for page configuration, navigation structure, and SEO. Custom components override default HTML elements to provide features like code copying, themed styling, and interactive examples.\n\nCustom components: `src/features/markdown/components/MDXComponents.tsx`\n\n## Commands\n\n### Monorepo Commands\n\n```bash\npnpm dev          # Start all applications\npnpm build        # Build all applications\npnpm lint         # Lint all applications\n```\n\n### Frontend Commands\n\n```bash\ncd apps/daraja-docs-platform\npnpm dev                # Start development server\npnpm build              # Build for production\npnpm start              # Start production server\npnpm type-check         # Run TypeScript type checking\npnpm build:analyze      # Analyze bundle size\n```\n\n### Backend Commands\n\n```bash\ncd apps/daraja-graphql-server\npnpm dev                    # Start development server\npnpm build                  # Compile TypeScript\npnpm start:apollo-server    # Start production server\n```\n\n## Deployment\n\n### Frontend\n\nThe frontend automatically deploys to Netlify when changes are merged to the `dev` branch. The deployment configuration is already set up in `netlify.toml`.\n\nFor new deployments, connect your repository to Netlify with these settings:\n\n- Build command: `npx turbo run build --filter=daraja-docs-platform`\n- Publish directory: `apps/daraja-docs-platform/.next`\n- Production branch: `dev`\n\n### Backend\n\nThe GraphQL server can be deployed to any Node.js hosting platform:\n\n```bash\ncd apps/daraja-graphql-server\npnpm build\npnpm start:apollo-server\n```\n\nConfigure environment variables on your hosting platform.\n\n## Architecture\n\n### Monorepo Structure\n\nThe project uses [Turborepo](https://turbo.build/repo/docs) with pnpm workspaces to manage multiple applications. Turborepo handles build orchestration and caching, while pnpm workspaces manage dependencies and linking between packages. This structure enables:\n\n- Shared TypeScript types between frontend and backend\n- Coordinated builds with dependency awareness\n- Selective task execution using filters\n- Build caching to speed up CI/CD pipelines\n\nThe workspace configuration is defined in `pnpm-workspace.yaml`, and build tasks are configured in `turbo.json`.\n\n### GraphQL Layer\n\nThe [GraphQL](https://graphql.org/learn/) server acts as a unified gateway, aggregating data from multiple sources:\n\n- **Daraja API** — Proxies requests to Safaricom's M-Pesa API\n- **GitHub API** — Fetches repository statistics and release information\n- **Hashnode/Dev.to** — Aggregates blog posts about M-Pesa integration\n\nEach data source is implemented using Apollo's RESTDataSource pattern, providing consistent error handling, caching, and request deduplication. The server runs on Express with Apollo Server middleware, handling authentication via request headers that are passed through to the context.\n\nThis architecture centralizes API logic, enabling the frontend to fetch related data in single GraphQL queries while the server handles rate limiting, authentication, and response transformation.\n\nImplementation: `apps/daraja-graphql-server/src/datasources.ts`\n\n### Context Providers\n\nThe frontend uses a nested provider architecture for state management. Providers are layered in `src/app/_components/_layout.tsx` in the following order:\n\n1. **AppThemeProvider** — MUI theme configuration and dark/light mode\n2. **ApolloClientProvider** — GraphQL client with cache configuration\n3. **AuthContextProvider** — User authentication state and session management\n4. **AppAIProvider** — AI assistant state and conversation history\n5. **VersionManagerContextProvider** — API version selection and routing\n\nProvider order matters because inner providers may depend on outer ones (e.g., Apollo depends on theme for loading states). Each provider exports custom hooks (`useAuth()`, `useAI()`, etc.) that should be used instead of accessing contexts directly. This pattern ensures proper type safety and prevents context access outside the provider tree.\n\n## Contributing\n\nContributions are welcome. Please follow the standard GitHub flow:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Submit a pull request\n\nPre-commit hooks will run automatically via Husky. Ensure your code passes linting and type checking before submitting.\n\nRun type checking:\n```bash\npnpm type-check\n```\n\n## Troubleshooting\n\n### Module Not Found Errors\n\nRestart the development server after installing new packages. Turbopack typically detects changes automatically, but manual restarts may occasionally be necessary.\n\n### Port Conflicts\n\nIf the GraphQL server fails to start, verify that port 4000 is available:\n\n```bash\n# macOS/Linux\nlsof -i :4000\n\n# Windows\nnetstat -ano | findstr :4000\n```\n\n### Build Memory Issues\n\nIncrease Node.js heap size if builds fail with memory errors:\n\n```bash\nNODE_OPTIONS=--max_old_space_size=4096 pnpm build\n```\n\n### Cache Issues\n\nClear Turborepo cache and rebuild if you encounter unexpected issues:\n\n```bash\nrm -rf apps/*/dist apps/*/.next apps/*/node_modules\npnpm install\npnpm build\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famoskyalo%2Fdaraja-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famoskyalo%2Fdaraja-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famoskyalo%2Fdaraja-docs/lists"}