{"id":29567268,"url":"https://github.com/ntanwir10/python-journal-api","last_synced_at":"2026-04-17T00:02:17.072Z","repository":{"id":300972227,"uuid":"1007714088","full_name":"ntanwir10/python-journal-api","owner":"ntanwir10","description":"A FastAPI-powered journal service that lets users securely manage their personal journal entries through a RESTful API. Built with Python and PostgreSQL, it features robust JWT authentication, email verification, and password reset capabilities.","archived":false,"fork":false,"pushed_at":"2025-07-12T20:49:31.000Z","size":65,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-12T22:24:57.885Z","etag":null,"topics":["api-rest","httpx","postgresql","pydantic-v2","pytest","python3","sqlalchemy-python"],"latest_commit_sha":null,"homepage":"","language":"Python","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/ntanwir10.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}},"created_at":"2025-06-24T12:19:19.000Z","updated_at":"2025-07-12T20:49:34.000Z","dependencies_parsed_at":"2025-06-24T14:41:45.571Z","dependency_job_id":"1cf2ebd7-27b3-42d1-8fba-7f058289ca29","html_url":"https://github.com/ntanwir10/python-journal-api","commit_stats":null,"previous_names":["ntanwir10/python-journal-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ntanwir10/python-journal-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ntanwir10%2Fpython-journal-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ntanwir10%2Fpython-journal-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ntanwir10%2Fpython-journal-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ntanwir10%2Fpython-journal-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ntanwir10","download_url":"https://codeload.github.com/ntanwir10/python-journal-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ntanwir10%2Fpython-journal-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31909235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"ssl_error","status_checked_at":"2026-04-16T18:21:47.142Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["api-rest","httpx","postgresql","pydantic-v2","pytest","python3","sqlalchemy-python"],"created_at":"2025-07-18T23:30:39.193Z","updated_at":"2026-04-17T00:02:17.053Z","avatar_url":"https://github.com/ntanwir10.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python FastAPI Journal API\n\nThe Journal API is a FastAPI-based REST service that enables users to maintain personal journal entries. Built with Python 3.11+ and PostgreSQL, it features a robust authentication system with JWT tokens, email verification, and password reset functionality. The API follows modern security practices and includes comprehensive test coverage. Both the authentication system and journal entry management features are fully implemented and functional. The project uses SQLAlchemy for database operations, Pydantic for data validation, and includes a full test suite with pytest.\n\nKey features:\n\n- Secure user authentication with JWT tokens\n- Email verification and password reset\n- PostgreSQL database with SQLAlchemy ORM\n- Comprehensive test coverage\n- API documentation via Swagger UI and ReDoc\n- Modern development workflow with formatting and linting tools\n\nInspired by [Learn To Cloud](https://learntocloud.guide/)'s [Journal Starter](https://github.com/learntocloud/journal-starter) capstone project. Rather than forking the repository, this is a from-scratch implementation.\n\n## Prerequisites\n\n- Python 3.11+\n- PostgreSQL 17\n- Poetry (optional)\n\n## Database Setup\n\n1. Install PostgreSQL 17:\n\n```bash\nbrew install postgresql@17\n```\n\n2. Start PostgreSQL service:\n\n```bash\nbrew services start postgresql@17\n```\n\n3. Add PostgreSQL to your PATH:\n\n```bash\necho 'export PATH=\"/opt/homebrew/opt/postgresql@17/bin:$PATH\"' \u003e\u003e ~/.zshrc\nsource ~/.zshrc\n```\n\n4. Run the automated database setup script:\n\n```bash\n./scripts/setup_db.sh\n```\n\nThis script will:\n\n- Create the main database (journal_db)\n- Create the test database (journal_api_test)\n- Set up necessary extensions\n- Apply all database migrations\n\nAlternatively, you can set up the databases manually:\n\n5. Create the database:\n\n```bash\ncreatedb journal_db\n```\n\n6. Create test database (for running tests):\n\n```bash\ncreatedb journal_api_test\n```\n\n7. Apply database migrations:\n\n```bash\nalembic upgrade head\n```\n\n## Environment Setup\n\n1. Create a virtual environment:\n\n```bash\npython -m venv venv\nsource venv/bin/activate\n```\n\n2. Install dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\n3. Create a `.env` file:\n\n```bash\ncp .env.example .env\n```\n\nThen edit `.env` with your database credentials and other settings:\n\n```JSON\nPOSTGRES_USER=your_username\nPOSTGRES_PASSWORD=your_password\nPOSTGRES_HOST=localhost\nPOSTGRES_PORT=5432\nPOSTGRES_DB=journal_db\nPOSTGRES_TEST_DB=journal_api_test\nSECRET_KEY=your_secret_key\nACCESS_TOKEN_EXPIRE_MINUTES=30\nREFRESH_TOKEN_EXPIRE_DAYS=7\nRESET_TOKEN_EXPIRE_MINUTES=15\nEMAIL_SENDER=your_email@example.com\nEMAIL_PASSWORD=your_email_app_password\nEMAIL_HOST=smtp.gmail.com\nEMAIL_PORT=587\n```\n\n## Project Structure\n\n```txt\njournal-api/\n├── app/                    # Application package\n│   ├── api/               # API routes and endpoints\n│   │   └── v1/           # Version 1 API endpoints\n│   │       ├── auth_endpoint.py      # Authentication endpoints\n│   │       └── journal_entry_endpoint.py  # Journal entry endpoints\n│   ├── core/              # Core functionality\n│   │   ├── config.py      # Application settings\n│   │   └── auth_middleware.py  # JWT authentication middleware\n│   ├── db/                # Database related files\n│   │   ├── base.py        # SQLAlchemy declarative base\n│   │   └── session.py     # Database session management\n│   ├── models/            # SQLAlchemy models\n│   │   ├── user_model.py  # User model\n│   │   └── journal_entry_model.py  # Journal entry model\n│   ├── schemas/           # Pydantic models/schemas\n│   │   ├── auth_schema.py # Authentication schemas\n│   │   └── journal_entry_schema.py # Journal entry schemas\n│   ├── services/          # Business logic layer\n│   │   ├── auth_service.py  # Authentication service\n│   │   ├── email_service.py # Email service\n│   │   └── journal_entry_service.py # Journal entry service\n│   └── main.py           # FastAPI application creation\n├── tests/                 # Test suite\n│   ├── conftest.py       # Test configuration and fixtures\n│   ├── test_auth.py      # Authentication tests\n│   ├── test_models.py    # Model tests\n│   └── test_journal_entries.py # Journal entry tests\n├── .env.example          # Example environment variables\n├── requirements.txt      # Project dependencies\n└── Makefile             # Development commands\n```\n\n## Technical Stack\n\n- **Core Framework**: Python 3.11+, FastAPI, Uvicorn\n- **Database**: PostgreSQL, SQLAlchemy, Alembic (migrations)\n- **Security**: Python-Jose (JWT), Passlib (bcrypt)\n- **Validation**: Pydantic v2\n- **Testing**: Pytest, httpx\n- **Development Tools**: Black (formatting), Flake8 (linting), isort (import sorting)\n\n## Development Workflow\n\n1. Create feature branch\n2. Implement feature/fix\n3. Run tests (`make test`)\n4. Format code (`make format`)\n5. Run linting (`make lint`)\n6. Create database migration if needed (`alembic revision --autogenerate -m \"description\"`)\n7. Apply migrations (`alembic upgrade head`)\n8. Commit changes\n9. Create pull request\n\n## Getting Started\n\n1. Clone the repository\n2. Copy `.env.example` to `.env` and update the values\n3. Install dependencies: `make install`\n4. Start the development server: `make dev`\n5. Run tests: `make test`\n\n## Implementation Status\n\n### ✅ Completed Features\n\n1. **Authentication System**\n   - User registration with email verification\n   - Login with JWT token generation\n   - Token refresh mechanism\n   - Password reset flow with email\n   - Secure password hashing with bcrypt\n   - Comprehensive test suite\n   - Rate limiting with configurable limits per endpoint type\n   - Security headers and CORS configuration\n\n2. **Journal Entry API**\n   - Complete CRUD operations for journal entries\n   - User-specific entry filtering and access control\n   - Entry validation and error handling\n   - UUID-based entry identification\n   - Timestamp tracking (created_at, updated_at)\n   - Bulk delete functionality\n\n3. **Database Infrastructure**\n   - Automated database setup script\n   - Database migrations with Alembic\n   - User model with UUID, email, and password\n   - Journal entry model with work, struggle, and intention fields\n   - Proper relationship setup between models\n\n4. **Testing Infrastructure**\n   - Test database configuration\n   - Database transaction fixtures\n   - Email service mocking\n   - Authentication test suite\n\n## 🎉 Project Status: Complete\n\nThis Journal API is **fully functional** with all core features implemented:\n\n- ✅ **Complete Authentication System** - Registration, login, token refresh, password reset\n- ✅ **Complete Journal Entry CRUD** - Create, read, update, delete operations\n- ✅ **User Authorization** - Secure access to user-specific journal entries\n- ✅ **Database Integration** - PostgreSQL with SQLAlchemy ORM\n- ✅ **Comprehensive Testing** - Full test suite with pytest\n- ✅ **API Documentation** - Auto-generated OpenAPI/Swagger docs\n- ✅ **Rate Limiting** - Protection against abuse\n- ✅ **Email Integration** - Password reset functionality\n\nThe API is production-ready and can be deployed immediately.\n\n## API Documentation\n\nOnce running, API documentation is available at:\n\n- Swagger UI: \u003chttp://localhost:8000/docs\u003e\n- ReDoc: \u003chttp://localhost:8000/redoc\u003e\n\n## API Endpoints\n\n### Authentication Endpoints\n\n| Method | Endpoint                | Description                              | Status     |\n| ------ | ----------------------- | ---------------------------------------- | ---------- |\n| POST   | `/auth/signup`          | Register a new user                      | ✅ Complete |\n| POST   | `/auth/login`           | Authenticate user and get tokens         | ✅ Complete |\n| POST   | `/auth/refresh`         | Get new access token using refresh token | ✅ Complete |\n| POST   | `/auth/logout`          | Invalidate current tokens                | ✅ Complete |\n| POST   | `/auth/forgot-password` | Request password reset email             | ✅ Complete |\n| POST   | `/auth/reset-password`  | Reset password using token from email    | ✅ Complete |\n\n### Journal Entry Endpoints\n\n| Method | Endpoint        | Description                               | Status     |\n| ------ | --------------- | ----------------------------------------- | ---------- |\n| POST   | `/entries`      | Create a new journal entry                | ✅ Complete |\n| GET    | `/entries`      | List all entries for authenticated user   | ✅ Complete |\n| GET    | `/entries/{id}` | Get a specific entry by ID                | ✅ Complete |\n| PUT    | `/entries/{id}` | Update an existing entry                  | ✅ Complete |\n| DELETE | `/entries/{id}` | Delete a specific entry                   | ✅ Complete |\n| DELETE | `/entries`      | Delete all entries for authenticated user | ✅ Complete |\n\n## Authentication API Examples\n\n```bash\n# Sign-up\ncurl -X POST http://localhost:8000/auth/signup \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"user@example.com\",\n    \"password\": \"securepassword123\"\n  }'\n```\n\n```bash\n# Login\ncurl -X POST http://localhost:8000/auth/login \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"user@example.com\",\n    \"password\": \"securepassword123\"\n  }'\n```\n\n```bash\n# Refresh Token\ncurl -X POST http://localhost:8000/auth/refresh \\\n  -H \"Authorization: Bearer YOUR_REFRESH_TOKEN\"\n```\n\n```bash\n# Logout (requires auth token)\ncurl -X POST http://localhost:8000/auth/logout \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n```\n\n```bash\n# Request Password Reset\ncurl -X POST http://localhost:8000/auth/forgot-password \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"user@example.com\"\n  }'\n```\n\n```bash\n# Reset Password (using reset token)\ncurl -X POST http://localhost:8000/auth/reset-password \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"token\": \"RESET_TOKEN_FROM_EMAIL\",\n    \"new_password\": \"newSecurePassword123\"\n  }'\n```\n\nNote: Replace `YOUR_ACCESS_TOKEN` and `YOUR_REFRESH_TOKEN` with the actual JWT tokens received from the login endpoint.\n\n## Journal Entry API Examples\n\n```bash\n# Create a new journal entry (requires authentication)\ncurl -X POST http://localhost:8000/api/v1/entries \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -d '{\n    \"work\": \"Completed the authentication system for the journal API\",\n    \"struggle\": \"Had some issues with JWT token validation initially\",\n    \"intention\": \"Tomorrow I will work on improving the error handling\"\n  }'\n```\n\n```bash\n# Get all journal entries for the authenticated user\ncurl -X GET http://localhost:8000/api/v1/entries \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n```\n\n```bash\n# Get a specific journal entry by ID\ncurl -X GET http://localhost:8000/api/v1/entries/ENTRY_UUID \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n```\n\n```bash\n# Update a journal entry\ncurl -X PUT http://localhost:8000/api/v1/entries/ENTRY_UUID \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -d '{\n    \"work\": \"Updated the journal entry endpoints\",\n    \"struggle\": \"Debugging some async database issues\",\n    \"intention\": \"Focus on adding comprehensive tests tomorrow\"\n  }'\n```\n\n```bash\n# Delete a specific journal entry\ncurl -X DELETE http://localhost:8000/api/v1/entries/ENTRY_UUID \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n```\n\n```bash\n# Delete all journal entries for the authenticated user\ncurl -X DELETE http://localhost:8000/api/v1/entries \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n```\n\nNote: Replace `YOUR_ACCESS_TOKEN` with the actual JWT access token received from the login endpoint, and `ENTRY_UUID` with the actual UUID of a journal entry.\n\n## Database Migrations\n\nThe project uses Alembic for database migrations. Here are common migration commands:\n\n```bash\n# Create a new migration\nalembic revision --autogenerate -m \"description of changes\"\n\n# Apply all pending migrations\nalembic upgrade head\n\n# Rollback last migration\nalembic downgrade -1\n\n# View migration history\nalembic history\n\n# View current migration status\nalembic current\n```\n\nAll migrations are stored in the `migrations/versions/` directory and are version controlled. This ensures consistent database schema across all environments.\n\nThe initial migration includes:\n\n- User table with UUID, email, and password fields\n- Journal entry table with work, struggle, and intention fields\n- Proper indexes and foreign key relationships\n- Timestamp fields for auditing\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fntanwir10%2Fpython-journal-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fntanwir10%2Fpython-journal-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fntanwir10%2Fpython-journal-api/lists"}