{"id":19844358,"url":"https://github.com/cenobites/flask-jsonrpc-sample","last_synced_at":"2026-06-23T17:32:19.946Z","repository":{"id":245326613,"uuid":"817909508","full_name":"cenobites/flask-jsonrpc-sample","owner":"cenobites","description":"Sample project for a library management system (LMS) using Flask-JSONRPC.","archived":false,"fork":false,"pushed_at":"2026-01-26T16:12:46.000Z","size":615,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-29T21:26:42.133Z","etag":null,"topics":["flask","flask-jsonrpc","jsonrpc","sample"],"latest_commit_sha":null,"homepage":"https://flask-jsonrpc.cenobit.es","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cenobites.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"nycholas"}},"created_at":"2024-06-20T17:37:40.000Z","updated_at":"2025-12-08T22:38:52.000Z","dependencies_parsed_at":"2024-06-21T12:27:20.403Z","dependency_job_id":"72a136c3-04ac-4bfc-a309-6c6d3627056b","html_url":"https://github.com/cenobites/flask-jsonrpc-sample","commit_stats":null,"previous_names":["cenobites/flask-jsonrpc-sample"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cenobites/flask-jsonrpc-sample","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cenobites%2Fflask-jsonrpc-sample","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cenobites%2Fflask-jsonrpc-sample/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cenobites%2Fflask-jsonrpc-sample/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cenobites%2Fflask-jsonrpc-sample/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cenobites","download_url":"https://codeload.github.com/cenobites/flask-jsonrpc-sample/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cenobites%2Fflask-jsonrpc-sample/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34700906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"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":["flask","flask-jsonrpc","jsonrpc","sample"],"created_at":"2024-11-12T13:03:49.571Z","updated_at":"2026-06-23T17:32:19.938Z","avatar_url":"https://github.com/cenobites.png","language":"Python","funding_links":["https://github.com/sponsors/nycholas"],"categories":[],"sub_categories":[],"readme":"# Library Management System (LMS)\n\nA modern, full-stack library management system built with Flask JSON-RPC API and Next.js UI in a monorepo architecture.\n\n## 🚀 Overview\n\nThis project provides a complete solution for managing library operations including catalog management, patron registration, circulation (checkouts/returns), branch management, staff administration, and more.\n\n### Architecture\n\n- **Backend**: Flask-based JSON-RPC 2.0 API (`apps/lms-api`)\n- **Frontend**: Next.js 16 with React 19 and TypeScript (`apps/lms-ui`)\n- **Monorepo**: Organized structure with independent apps sharing common infrastructure\n\n## 📦 Project Structure\n\n```\nflask-jsonrpc-sample/\n├── apps/\n│   ├── lms-api/          # Flask JSON-RPC API backend\n│   │   ├── src/lms/      # Application source code\n│   │   ├── migrations/   # Database migrations\n│   │   └── README.md     # API documentation\n│   └── lms-ui/           # Next.js frontend\n│       ├── app/          # Next.js app router pages\n│       ├── components/   # Reusable React components\n│       ├── lib/          # API clients, schemas, utilities\n│       └── README.md     # UI documentation\n├── compose.yml           # Docker Compose configuration\n└── README.md             # This file\n```\n\n## ✨ Features\n\n### Core Modules\n\n- **📚 Catalog Management**: Manage books, DVDs, magazines, and other library materials\n- **👥 Patron Management**: Register and manage library members with card tracking\n- **🔄 Circulation**: Handle checkouts, returns, renewals, and holds\n- **🏢 Branch Management**: Manage multiple library locations\n- **👔 Staff Management**: Administer library employees with role-based access\n- **📦 Acquisitions**: Manage purchase orders and vendors\n- **📰 Serials Management**: Track magazines, journals, and subscriptions\n- **📊 Reports**: Generate statistics and usage reports\n- **💰 Fines Management**: Track and manage patron fines\n\n### Technical Features\n\n- **JSON-RPC 2.0**: Standardized API communication protocol\n- **Type-Safe**: Full TypeScript implementation with Zod validation\n- **Modern UI**: Responsive design with Tailwind CSS\n- **Real-time Updates**: React Query for efficient data synchronization\n- **Modular Architecture**: Clean separation of concerns\n- **Docker Support**: Easy deployment with Docker Compose\n\n## 🛠️ Tech Stack\n\n### Backend (lms-api)\n\n- **Framework**: Flask 3.x\n- **API**: Flask-JSONRPC\n- **Database**: SQLAlchemy ORM (PostgreSQL/MySQL/SQLite)\n- **Validation**: Pydantic/Marshmallow schemas\n- **Architecture**: Clean Architecture (Entities, Repositories, Services)\n\n### Frontend (lms-ui)\n\n- **Framework**: Next.js 16 (App Router)\n- **Language**: TypeScript with strict mode\n- **Styling**: Tailwind CSS 4\n- **State Management**: TanStack Query (React Query)\n- **Validation**: Zod schemas\n- **API Client**: Axios with JSON-RPC support\n- **Icons**: Lucide React\n\n## 🚦 Quick Start\n\n### Prerequisites\n\n- **Backend**: Python 3.10+, uv or pip\n- **Frontend**: Node.js 20+, npm or yarn\n- **Optional**: Docker \u0026 Docker Compose\n\n### Option 1: Docker Compose (Recommended)\n\n1. Clone the repository:\n\n```bash\ngit clone \u003crepository-url\u003e\ncd flask-jsonrpc-sample\n```\n\n2. Start all services:\n\n```bash\ndocker-compose up --build\n```\n\n3. Access the applications:\n   - **API**: http://localhost:5000/api\n   - **UI**: http://localhost:3000\n\n### Option 2: Manual Setup\n\n#### Backend Setup\n\n```bash\ncd apps/lms-api\n\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install dependencies\npip install -e .\n\n# Run migrations\nflask db upgrade\n\n# Start the server\nflask --app run run --debug\n```\n\nThe API will be available at http://localhost:5000/api\n\n#### Frontend Setup\n\n```bash\ncd apps/lms-ui\n\n# Install dependencies\nnpm install\n\n# Configure environment\ncp .env.example .env.local\n# Edit .env.local and set NEXT_PUBLIC_API_URL=http://localhost:5000/api\n\n# Start development server\nnpm run dev\n```\n\nThe UI will be available at http://localhost:3000\n\n## 📖 API Documentation\n\nThe API follows JSON-RPC 2.0 specification. Key namespaces:\n\n### Organizations\n- `Branches.*` - Branch management (list, get, create, update, delete)\n- `Staff.*` - Staff management\n\n### Patrons\n- `Patrons.*` - Patron management\n\n### Catalog\n- `Items.*` - Bibliographic items (books, DVDs, etc.)\n- `Copies.*` - Physical copies of items\n\n### Circulation\n- `Loans.*` - Checkout/checkin/renewal operations\n- `Holds.*` - Reservation management\n\n### Acquisitions\n- `Vendors.*` - Vendor management\n- `AcquisitionOrders.*` - Purchase order management\n\n### Serials\n- `Serials.*` - Serial publication management\n- `SerialIssues.*` - Individual issue tracking\n\nFor detailed API documentation, see [apps/lms-api/README.md](./apps/lms-api/README.md)\n\n## 🎨 UI Pages\n\n- **Dashboard** (`/`) - Library statistics and quick actions\n- **Catalog** (`/catalog`) - Browse and manage items\n- **Patrons** (`/patrons`) - Member management\n- **Circulation** (`/circulation`) - Loans and holds\n- **Branches** (`/branches`) - Location management\n- **Staff** (`/staff`) - Employee directory\n\nFor UI documentation, see [apps/lms-ui/README.md](./apps/lms-ui/README.md)\n\n## 🧪 Development\n\n### Backend Development\n\n```bash\ncd apps/lms-api\n\n# Run tests\npytest\n\n# Format code\nblack src/\n\n# Lint code\nflake8 src/\n\n# Type checking\nmypy src/\n```\n\n### Frontend Development\n\n```bash\ncd apps/lms-ui\n\n# Run in development mode\nnpm run dev\n\n# Build for production\nnpm run build\n\n# Start production server\nnpm start\n\n# Run linting\nnpm run lint\n\n# Type checking\nnpx tsc --noEmit\n```\n\n## 🐳 Docker Support\n\n### Build and run with Docker Compose:\n\n```bash\n# Start all services\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f\n\n# Stop services\ndocker-compose down\n```\n\n### Individual container builds:\n\n```bash\n# Backend only\ndocker build -f apps/lms-api/Dockerfile -t lms-api .\ndocker run -p 5000:5000 lms-api\n\n# Frontend only\ndocker build -f apps/lms-ui/Dockerfile -t lms-ui .\ndocker run -p 3000:3000 lms-ui\n```\n\n## 📝 Environment Variables\n\n### Backend (.env)\n\n```env\nDATABASE_URL=sqlite:///lms.db\nSECRET_KEY=your-secret-key\nDEBUG=True\nFLASK_APP=run\n```\n\n### Frontend (.env.local)\n\n```env\nNEXT_PUBLIC_API_URL=http://localhost:5000/api\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nPlease read [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) for details on our code of conduct.\n\n## 📄 License\n\nThis project is licensed under the terms specified in [LICENSE.txt](./LICENSE.txt).\n\n## 👥 Authors\n\nSee [AUTHORS](./AUTHORS) for the list of contributors.\n\n## 🔗 Links\n\n- **API Documentation**: [apps/lms-api/README.md](./apps/lms-api/README.md)\n- **UI Documentation**: [apps/lms-ui/README.md](./apps/lms-ui/README.md)\n- **Implementation Guide**: [apps/lms-ui/IMPLEMENTATION.md](./apps/lms-ui/IMPLEMENTATION.md)\n- **Quick Start Guide**: [apps/lms-ui/QUICKSTART.md](./apps/lms-ui/QUICKSTART.md)\n\n## 🆘 Support\n\nFor issues, questions, or contributions, please open an issue on the repository.\n\n---\n\n**Built with ❤️ using Flask, Next.js, and modern web technologies**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcenobites%2Fflask-jsonrpc-sample","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcenobites%2Fflask-jsonrpc-sample","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcenobites%2Fflask-jsonrpc-sample/lists"}