Loading Project....
The tioelvis-api project addresses the common challenge developers face in maintaining up-to-date and thorough documentation for their diverse projects. By integrating seamlessly with GitHub and leveraging the advanced capabilities of Google's Gemini AI, this API streamlines the entire process of generating detailed project overviews and structured documentation sections. It acts as the core engine for a personal development blog, enabling the owner to effortlessly publish insights, technical deep-dives, and project showcases. From fetching repository files to processing them with AI and storing the generated content in a structured MongoDB database, tioelvis-api provides a powerful, automated solution for developer advocacy and knowledge sharing, allowing creators to focus more on building and less on manual documentation.
Before you begin, ensure you have the following software installed and configured on your system.
This project is built with Node.js. It's recommended to use the latest LTS version. You can download it from the official Node.js website or use a version manager like nvm.
node -v
npm -v
The API uses MongoDB as its database. You'll need a running MongoDB instance, either locally or a cloud-hosted solution like MongoDB Atlas. Ensure your MongoDB URI is accessible.
The application relies on several environment variables for configuration, including database connection strings, API keys, and security secrets. These will be detailed in the Configuration section.
Follow these steps to set up and run the tioelvis-api locally.
First, clone the project repository to your local machine:
git clone https://github.com/TioElvis/tioelvis-api.git
cd tioelvis-api
Install the required Node.js packages using npm:
npm install
Create a .env file in the root of the project and populate it with the necessary environment variables. Refer to the Configuration section for details on each variable.
touch .env
Once dependencies are installed and your .env is configured, you can start the application. For local development with hot-reloading, use:
npm run start:dev
The API will typically run on http://localhost:9000 (or the PORT specified in your .env).
The tioelvis-api uses environment variables for sensitive information and configurable settings. Create a .env file in the project root and define the following variables:
DB_URI="mongodb://localhost:27017/your-database"
DB_NAME="your-database-name"
DB_URI: The connection string for your MongoDB instance.DB_NAME: The name of the database to use.JWT_SECRET="a-very-secret-jwt-key"
COOKIE_SECRET="a-very-secret-cookie-key"
WEB_DOMAIN="yourblog.com" # Used for CORS and cookie domain in production
JWT_SECRET: A strong secret key for signing JWTs.COOKIE_SECRET: A strong secret key for signing cookies (used by Fastify).WEB_DOMAIN: The domain of your frontend application. Crucial for CORS and setting secure cookies in production environments.GITHUB_TOKEN="your_github_personal_access_token"
GITHUB_OWNER="TioElvis" # Your GitHub username
GITHUB_TOKEN: A GitHub Personal Access Token with repo scope to access your repositories.GITHUB_OWNER: Your GitHub username, used to filter repositories.GEMINI_KEY="your_google_gemini_api_key"
GEMINI_MODEL="gemini-pro" # e.g., gemini-pro, gemini-1.5-flash
GEMINI_KEY: Your API key for Google Gemini.GEMINI_MODEL: The specific Gemini model to use for content generation.PORT=9000
NODE_ENV="development" # or "production"
PORT: The port on which the API server will listen.NODE_ENV: Set to production for production deployments to enable secure cookie settings and specific CORS policies.The project follows a modular structure typical for NestJS applications. Here's an overview of the main directories and their purposes:
tioelvis-api/
├── src/
│ ├── app.controller.ts # Main application controller (health check)
│ ├── app.module.ts # Main application module, imports all other modules
│ ├── lib/ # Utility functions and constants
│ │ └── constants.ts # Global constants like JWT age, ignored paths, Gemini prompt
│ ├── main.ts # Application entry point, Fastify setup, CORS, global pipes
│ ├── modules/ # Feature-specific modules
│ │ ├── auth/ # Authentication (sign-in, sign-out, JWT)
│ │ │ ├── dto/ # Data Transfer Objects for auth
│ │ │ ├── auth.controller.ts
│ │ │ ├── auth.module.ts
│ │ │ ├── auth.service.ts
│ │ │ └── user.schema.ts # Mongoose schema for User
│ │ ├── gemini/ # AI documentation generation using Google Gemini
│ │ │ ├── dto/ # DTOs for Gemini requests
│ │ │ ├── gemini.controller.ts
│ │ │ ├── gemini.module.ts
│ │ │ └── gemini.service.ts
│ │ ├── github/ # GitHub API integration (repo listing, file fetching)
│ │ │ ├── github.controller.ts
│ │ │ ├── github.module.ts
│ │ │ └── github.service.ts
│ │ ├── project/ # Project management (CRUD for documentation projects)
│ │ │ ├── dto/ # DTOs for project operations
│ │ │ ├── project.controller.ts
│ │ │ ├── project.module.ts
│ │ │ ├── project.schema.ts # Mongoose schema for Project
│ │ │ └── project.service.ts
│ │ └── section/ # Documentation section management (CRUD, hierarchical)
│ │ ├── dto/ # DTOs for section operations
│ │ ├── section.controller.ts
│ │ ├── section.module.ts
│ │ ├── section.schema.ts # Mongoose schema for Section
│ │ └── section.service.ts
│ └── strategies/ # Passport.js strategies
│ └── jwt.strategy.ts # JWT authentication strategy
├── .env.example # Example environment variables
├── nest-cli.json # NestJS CLI configuration
├── package.json # Project dependencies and scripts
├── tsconfig.json # TypeScript configuration
└── ... (other config files like eslint, prettier)
IGNORED_PATHS list.Project entities, which represent documented repositories. It supports CRUD operations and allows querying projects by various criteria.Section entities. Sections are children of projects and can have nested children, forming a tree-like documentation structure.The tioelvis-api exposes several endpoints to manage projects, sections, and interact with external services like GitHub and Google Gemini. All endpoints requiring authentication are protected by JWT.
Authenticates a user and sets a signed JWT cookie.
POST /auth/sign-in
Request Body:
{
"username": "admin",
"password": "password123"
}
Response:
{
"message": "Signed in successfully."
}
Clears the JWT cookie, effectively logging out the user.
POST /auth/sign-out
Response:
{
"message": "Signed out successfully."
}
Checks if the provided JWT token (via cookie) is valid.
GET /auth/verify-jwt (Requires Authentication)
Response:
{
"message": "JWT is valid"
}
Fetches a list of repositories for the authenticated GitHub user, indicating which ones are already published as projects.
GET /github/find-all-repos (Requires Authentication)
Response Example:
{
"message": "Repositories fetched successfully.",
"data": [
{
"name": "my-awesome-project",
"description": "A project that does awesome things.",
"owner": "TioElvis",
"url": "https://github.com/TioElvis/my-awesome-project",
"isPublished": true,
"_id": "65d2a0b7e1f2c3d4e5f6a7b8",
"slug": "my-awesome-project"
},
{
"name": "another-repo",
"description": "Another project.",
"owner": "TioElvis",
"url": "https://github.com/TioElvis/another-repo",
"isPublished": false,
"_id": null,
"slug": null
}
]
}
This powerful endpoint leverages Google Gemini to analyze a GitHub repository and automatically generate comprehensive documentation, which is then saved as a Project and its Sections.
POST /gemini/generate (Requires Authentication)
Request Body:
{
"name": "your-repository-name",
"additionalPrompt": "Focus on the API endpoints and usage examples."
}
name: The name of the GitHub repository to document.additionalPrompt (optional): Any specific instructions or focus areas for the AI.Process Flow:
src/lib/constants.ts), are sent to the Google Gemini API.project details and an array of sections.Project and its associated Section hierarchy.Response Example:
{
"message": "Project generated successfully.",
"data": {
"title": "Your Repository Name",
"slug": "your-repository-name",
"description": "Generated description...",
"tags": ["tag1", "tag2"],
"content": "Generated markdown content...",
"languages": ["TypeScript"],
"repositoryUrl": "https://github.com/TioElvis/your-repository-name",
"_id": "65d2a0b7e1f2c3d4e5f6a7b8",
"createdAt": "2023-01-01T00:00:00.000Z",
"updatedAt": "2023-01-01T00:00:00.000Z",
"__v": 0
}
}
Manage your documented projects.
Manage individual documentation sections within a project.
The package.json includes several scripts to help with development, building, and running the application.
npm run start:devStarts the application in development mode with file watching and hot-reloading. Ideal for active development.
npm run start:dev
npm run start:debugStarts the application in debug mode with file watching. Useful for debugging with a Node.js debugger.
npm run start:debug
npm run formatFormats TypeScript and test files using Prettier.
npm run format
npm run lintLints TypeScript files across src, apps, libs, and test directories, automatically fixing issues where possible.
npm run lint
npm run buildCompiles the TypeScript source code into JavaScript, outputting to the dist directory.
npm run build
npm run startStarts the application without watch mode. Typically used after a build for testing or staging environments.
npm run start
npm run start:prodStarts the compiled production build of the application. This should be used in production environments.
npm run start:prod