Skip to content

Commit a61de3c

Browse files
gjovanovicstgjovanovicst
committed
docs: Create README for implementation phases
- Added README file to summarize the development phases of the project. Add project docs, issue templates, and contribution guides Establishes clear documentation for API, architecture, security, and development workflow. Introduces GitHub templates for issues and pull requests, a code of conduct, and contribution guidelines to streamline collaboration and onboarding. Organizes implementation phase plans for structured development and enhanced project transparency. Add project docs, contribution guides, and issue templates Establishes comprehensive documentation for API, architecture, security, and development workflow. Introduces templates for issues and pull requests, a code of conduct, and contribution guidelines to improve collaboration and onboarding. Organizes detailed implementation plans into structured development phases for enhanced transparency.
1 parent c99d0aa commit a61de3c

17 files changed

+283
-0
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
name: Bug Report
3+
about: Create a report to help us improve
4+
labels: bug
5+
---
6+
7+
**Describe the bug**
8+
A clear and concise description of what the bug is.
9+
10+
**To Reproduce**
11+
Steps to reproduce the behavior:
12+
1. API endpoint called: `POST /api/your-endpoint`
13+
2. Request payload (if any):
14+
```json
15+
{
16+
"key": "value"
17+
}
18+
```
19+
3. Request headers (if any):
20+
```
21+
Authorization: Bearer <token>
22+
```
23+
4. Relevant environment variables or configuration:
24+
```
25+
DB_HOST=...
26+
JWT_SECRET=...
27+
```
28+
5. Run the request (e.g., with curl, Postman, or frontend)
29+
6. See error/response:
30+
```json
31+
{
32+
"error": "..."
33+
}
34+
```
35+
7. (Optional) Include relevant logs or stack traces:
36+
```
37+
[2025-06-21 12:00:00] ERROR ...
38+
```
39+
40+
**Expected behavior**
41+
A clear and concise description of what you expected to happen.
42+
43+
**Screenshots**
44+
If applicable, add screenshots to help explain your problem.
45+
46+
**Environment (please complete the following information):**
47+
- OS: [e.g. Windows, Mac, Linux]
48+
- Go version: [e.g. 1.22]
49+
- Docker version: [if applicable]
50+
51+
**Additional context**
52+
Add any other context about the problem here.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
name: Feature Request
3+
about: Suggest an idea for this project
4+
labels: enhancement
5+
---
6+
7+
**Is your feature request related to a problem? Please describe.**
8+
A clear and concise description of what the problem is.
9+
10+
**Describe the solution you'd like**
11+
A clear and concise description of what you want to happen.
12+
13+
**Describe alternatives you've considered**
14+
A clear and concise description of any alternative solutions or features you've considered.
15+
16+
**Additional context**
17+
Add any other context or screenshots about the feature request here.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Pull Request
2+
3+
Thank you for your contribution!
4+
5+
## Description
6+
Please include a summary of the change and which issue is fixed. Also include relevant motivation and context.
7+
8+
Fixes # (issue)
9+
10+
## Type of change
11+
- [ ] Bug fix
12+
- [ ] New feature
13+
- [ ] Breaking change
14+
- [ ] Documentation update
15+
- [ ] Other (please describe):
16+
17+
## Checklist
18+
- [ ] My code follows the style guidelines of this project
19+
- [ ] I have performed a self-review of my code
20+
- [ ] I have commented my code, particularly in hard-to-understand areas
21+
- [ ] I have made corresponding changes to the documentation
22+
- [ ] My changes generate no new warnings
23+
- [ ] I have added tests that prove my fix is effective or that my feature works
24+
- [ ] New and existing unit tests pass locally with my changes
25+
- [ ] Any dependent changes have been merged and published in downstream modules
26+
27+
## Additional context
28+
Add any other context or screenshots about the pull request here.

‎CODE_OF_CONDUCT.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
6+
7+
## Our Standards
8+
9+
Examples of behavior that contributes to a positive environment:
10+
- Using welcoming and inclusive language
11+
- Being respectful of differing viewpoints
12+
- Gracefully accepting constructive criticism
13+
- Showing empathy towards others
14+
15+
Examples of unacceptable behavior:
16+
- Trolling, insulting/derogatory comments
17+
- Public or private harassment
18+
- Publishing others' private information
19+
20+
## Enforcement
21+
22+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project maintainer.
23+
24+
---
25+
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/).

‎CONTRIBUTING.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Contributing to Authentication API
2+
3+
Thank you for your interest in contributing! We welcome pull requests, issues, and suggestions to make this project better.
4+
5+
## How to Contribute
6+
7+
1. **Fork the repository** and create your branch from `main` or `develop`.
8+
2. **Clone your fork** and set up the project locally (see README for instructions).
9+
3. **Create a descriptive branch name** (e.g., `feature/social-login`, `fix/email-verification-bug`).
10+
4. **Make your changes** with clear, concise commits.
11+
5. **Test your changes** using `make test` or `go test ./...`.
12+
6. **Lint and format** your code: `make fmt` and `make lint`.
13+
7. **Push to your fork** and open a pull request (PR) against the `develop` branch.
14+
8. **Describe your PR** clearly, referencing any related issues.
15+
16+
## Code Style
17+
- Follow Go best practices and idioms.
18+
- Use `go fmt` for formatting.
19+
- Write clear, descriptive commit messages.
20+
- Add/update tests for new features or bug fixes.
21+
22+
## Reporting Issues
23+
- Use the GitHub Issues tab.
24+
- Provide as much detail as possible (steps to reproduce, logs, screenshots).
25+
26+
## Code of Conduct
27+
Please be respectful and inclusive. See `CODE_OF_CONDUCT.md` for details.
28+
29+
---
30+
Thank you for helping make this project better!

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎SECURITY.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Security Policy
2+
3+
## Reporting a Vulnerability
4+
5+
If you discover a security vulnerability, please open an issue or contact the maintainer directly. We will respond as quickly as possible to address the issue.
6+
7+
- Do not disclose security issues publicly until they have been resolved.
8+
- Provide as much detail as possible to help us resolve the issue quickly.
9+
10+
Thank you for helping keep this project secure!

‎docs/API.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# API Documentation
2+
3+
## Authentication Endpoints
4+
5+
### Register
6+
- `POST /register`
7+
- Request: `{ "email": "[email protected]", "password": "..." }`
8+
- Response: `{ "success": true, "data": { "token": "..." } }`
9+
10+
### Login
11+
- `POST /login`
12+
- Request: `{ "email": "[email protected]", "password": "..." }`
13+
- Response: `{ "success": true, "data": { "token": "..." } }`
14+
15+
### Refresh Token
16+
- `POST /refresh-token`
17+
- Request: `{ "refresh_token": "..." }`
18+
- Response: `{ "success": true, "data": { "token": "..." } }`
19+
20+
### Forgot Password
21+
- `POST /forgot-password`
22+
- Request: `{ "email": "[email protected]" }`
23+
- Response: `{ "success": true }`
24+
25+
### Reset Password
26+
- `POST /reset-password`
27+
- Request: `{ "token": "...", "new_password": "..." }`
28+
- Response: `{ "success": true }`
29+
30+
### Email Verification
31+
- `GET /verify-email?token=...`
32+
- Response: `{ "success": true }`
33+
34+
### Social Login
35+
- `GET /auth/{provider}/login`
36+
- `GET /auth/{provider}/callback`
37+
38+
### Protected Profile
39+
- `GET /profile`
40+
- Header: `Authorization: Bearer <token>`
41+
- Response: `{ "success": true, "data": { ...user... } }`
42+
43+
---
44+
For more details, see the OpenAPI spec (if available) or code comments.

‎docs/ARCHITECTURE.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Architecture Overview
2+
3+
## High-Level Diagram
4+
5+
```
6+
+-----------+ +-----------+ +-----------+
7+
| Client |<---> | API |<---> | Database |
8+
| (Frontend)| | (Gin) | | (Postgres)|
9+
+-----------+ +-----------+ +-----------+
10+
|
11+
v
12+
+-----------+
13+
| Redis |
14+
+-----------+
15+
```
16+
17+
- **API**: Go (Gin), handles authentication, authorization, and business logic
18+
- **Database**: PostgreSQL, stores users, tokens, etc.
19+
- **Redis**: Session/token management, caching
20+
- **Email**: SMTP for verification and password reset
21+
- **Social Auth**: OAuth2 with Google, Facebook, GitHub
22+
23+
## Key Components
24+
- `internal/auth` — Core authentication logic
25+
- `internal/user` — User management
26+
- `internal/social` — Social login
27+
- `internal/email` — Email verification/reset
28+
- `internal/middleware` — JWT, RBAC, etc.
29+
- `pkg/jwt` — JWT helpers
30+
31+
## Flow Example
32+
1. User registers or logs in
33+
2. API validates credentials, issues JWT
34+
3. JWT used for protected endpoints
35+
4. Redis manages sessions/tokens
36+
5. Social login handled via OAuth2 callback
37+
38+
---
39+
For more details, see the code and comments in each package.

‎docs/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Documentation
2+
3+
- [Architecture](ARCHITECTURE.md)
4+
- [API Reference](API.md)
5+
- [Development Phases](phases/)
6+
7+
See each file for details on architecture, endpoints, and implementation plans.

0 commit comments

Comments
 (0)