From 0c43525f86dcc984ff14d4dee6a228bf562e3f4f Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 4 Aug 2025 02:37:17 +0000 Subject: [PATCH] docs: Add comprehensive README.md with project documentation - Add detailed project overview and features - Include installation and setup instructions - Document API endpoints and usage examples - Add accounting structure and transaction examples - Include development guidelines and deployment notes - Add security considerations and contributing guidelines --- README.md | 249 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..3929534 --- /dev/null +++ b/README.md @@ -0,0 +1,249 @@ +# Medici Credit System + +A double-entry accounting system built with Node.js, Express, and MongoDB using the [Medici](https://github.com/flash-oss/medici) library for robust financial transaction management. + +## ๐Ÿ“‹ Overview + +This project implements a credit system using double-entry bookkeeping principles. It provides a RESTful API for managing financial transactions with automatic journal entries, ensuring accurate accounting records and financial integrity. + +## ๐Ÿš€ Features + +- **Double-Entry Bookkeeping**: Automatic debit/credit entries following accounting principles +- **MongoDB Integration**: Persistent storage for all financial records +- **Express API**: RESTful endpoints for transaction management +- **Journal Entries**: Detailed transaction logging with metadata support +- **Real-time Processing**: Immediate transaction processing and validation + +## ๐Ÿ› ๏ธ Technologies Used + +- **Node.js** - Runtime environment +- **Express.js** - Web framework +- **MongoDB** - Database for transaction storage +- **Mongoose** - MongoDB object modeling +- **Medici** - Double-entry accounting library +- **dotenv** - Environment variable management + +## ๐Ÿ“ฆ Installation + +### Prerequisites + +- Node.js (v14 or higher) +- MongoDB (running instance) +- npm or yarn package manager + +### Setup + +1. **Clone the repository** + ```bash + git clone + cd medici_credit_system + ``` + +2. **Install dependencies** + ```bash + npm install + ``` + +3. **Environment Configuration** + Create a `.env` file in the root directory: + ```env + PORT=4000 + USE_MEMORY_REPL_SET=false + MONGODB_URI=mongodb://172.31.5.177:27017/?readPreference=primary&directConnection=true&ssl=false&authMechanism=DEFAULT + ``` + +4. **Start the server** + ```bash + # Development mode with auto-reload + npm run credit + + # Or standard start + node server.js + ``` + +## ๐Ÿ”ง Usage + +### Basic Transaction Example + +The system automatically creates journal entries when you make requests to the API endpoints. + +**GET /** - Create a sample transaction +```bash +curl http://localhost:4000/ +``` + +This endpoint demonstrates a basic transaction: +- **Debit**: Assets:Cash account with $1000 +- **Credit**: Income account with $1000 +- **Metadata**: Client information (Joe Blow) + +### Response Format + +```json +{ + "status": "success" +} +``` + +## ๐Ÿ“Š Accounting Structure + +### Chart of Accounts + +The system supports standard accounting categories: + +- **Assets** (Debit increases, Credit decreases) + - Cash + - Accounts Receivable + - Inventory + +- **Liabilities** (Credit increases, Debit decreases) + - Accounts Payable + - Loans Payable + +- **Equity** (Credit increases, Debit decreases) + - Owner's Equity + - Retained Earnings + +- **Income** (Credit increases, Debit decreases) + - Sales Revenue + - Service Income + +- **Expenses** (Debit increases, Credit decreases) + - Operating Expenses + - Cost of Goods Sold + +### Transaction Example + +```javascript +const myBook = new Book("MyBook"); +const journal = await myBook + .entry("Received payment") + .debit("Assets:Cash", 1000) + .credit("Income", 1000, { client: "Joe Blow" }) + .commit(); +``` + +## ๐Ÿ—„๏ธ Database Schema + +The Medici library automatically creates the following collections in MongoDB: + +- **medici_transactions** - Individual transaction records +- **medici_journals** - Journal entry headers +- **medici_books** - Book/ledger definitions + +## ๐Ÿ” API Endpoints + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/` | Create sample transaction and return success status | + +*Note: This is a basic implementation. Additional endpoints can be added for full CRUD operations.* + +## ๐Ÿšฆ Development + +### Scripts + +```bash +# Start development server with auto-reload +npm run credit + +# Run tests (not implemented yet) +npm test +``` + +### Adding New Endpoints + +To add new transaction endpoints, follow this pattern: + +```javascript +app.post('/transaction', async (req, res) => { + try { + const { description, debitAccount, creditAccount, amount, metadata } = req.body; + + const myBook = new Book("MyBook"); + const journal = await myBook + .entry(description) + .debit(debitAccount, amount) + .credit(creditAccount, amount, metadata) + .commit(); + + res.status(200).json({ + status: "success", + journalId: journal._id + }); + } catch (error) { + res.status(500).json({ error: error.message }); + } +}); +``` + +## ๐Ÿงช Testing + +Currently, no tests are implemented. To add testing: + +1. Install testing framework: + ```bash + npm install --save-dev jest supertest + ``` + +2. Update package.json test script: + ```json + "scripts": { + "test": "jest" + } + ``` + +## ๐Ÿ”’ Security Considerations + +- **Database Security**: Ensure MongoDB is properly secured in production +- **Input Validation**: Add validation for all transaction inputs +- **Authentication**: Implement user authentication for production use +- **Environment Variables**: Keep sensitive data in environment variables + +## ๐Ÿš€ Deployment + +### Production Setup + +1. **Environment Variables** + ```env + NODE_ENV=production + PORT=3000 + MONGODB_URI=your-production-mongodb-uri + ``` + +2. **Process Management** + Consider using PM2 for production: + ```bash + npm install -g pm2 + pm2 start server.js --name "medici-credit-system" + ``` + +## ๐Ÿค Contributing + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request + +## ๐Ÿ“„ License + +This project is licensed under the ISC License. + +## ๐Ÿ“ž Support + +For support and questions: +- Create an issue in the repository +- Check the [Medici documentation](https://github.com/flash-oss/medici) +- Review MongoDB connection troubleshooting guides + +## ๐Ÿ”— Related Resources + +- [Medici Library Documentation](https://github.com/flash-oss/medici) +- [Double-Entry Bookkeeping Principles](https://en.wikipedia.org/wiki/Double-entry_bookkeeping) +- [Express.js Documentation](https://expressjs.com/) +- [MongoDB Documentation](https://docs.mongodb.com/) + +--- + +**Note**: This is a development version. Ensure proper security measures and testing before deploying to production. \ No newline at end of file