Skip to content

AGENTS.md

Latest commit

 

History

History
109 lines (93 loc) · 5.72 KB

AGENTS.md

File metadata and controls

109 lines (93 loc) · 5.72 KB
Raw

BNET Digital Bookkeeping — Agent Guide

Project structure

PembukuanDigital/
├── backend/           # Lumen 10 PHP API (all code lives here)
│   ├── app/
│   │   ├── Http/Controllers/Api/   # Controllers
│   │   ├── Services/                # Business logic layer
│   │   ├── Repositories/            # Data access layer (extends BaseRepository)
│   │   ├── Models/                  # Eloquent models (10 models)
│   │   ├── Http/Middleware/         # jwt, admin, employee, cors
│   │   └── Providers/               # AuthServiceProvider (Gates: admin, owner)
│   ├── config/                      # auth.php, cors.php, database.php
│   ├── database/
│   │   ├── migrations/              # 10 migrations (numbered 000001-000010)
│   │   └── seeders/                 # Roles, Users, Packages, PaymentMethods, Settings
│   ├── routes/api.php               # All API routes under /api prefix
│   ├── .env                         # Not committed (copy from .env.example)
│   └── composer.json                # PHP ^8.1, lumen ^10, firebase/php-jwt ^7.1
├── frontend/          # React + Vite SPA (Tailwind CSS v4)
│   ├── src/
│   │   ├── components/
│   │   │   ├── ui/          # Reusable: Button, Card, Input, Select, Badge,
│   │   │   │                # Modal, Table, Toast, EmptyState, Skeleton, Loading, Pagination
│   │   │   └── layout/      # Sidebar, Navbar, MainLayout
│   │   ├── pages/           # Dashboard, Customers, CustomerDetail, Packages,
│   │   │                    # Billing, Payments, Reports, Arrears, Settings
│   │   ├── contexts/        # AuthContext (login/logout/JWT)
│   │   ├── services/        # api.js (Axios instance + interceptors)
│   │   ├── utils/           # format.js (formatRupiah, formatDate, formatMonth)
│   │   ├── App.jsx          # React Router config
│   │   ├── main.jsx
│   │   └── index.css        # Tailwind @theme with DESIGN.md tokens
│   ├── vite.config.js       # Proxy /api -> localhost:8000
│   ├── package.json
│   └── index.html
├── create_db.php                    # Creates MySQL database bnet_bookkeeping
├── test_api.php                     # JWT smoke test
└── DESIGN.md                        # Apple-inspired design system (applied in frontend/)

Commands

# All commands run from backend/
cd backend

# Copy .env and configure
cp .env.example .env    # then edit DB_*, JWT_SECRET

# Install
composer install

# Create database (from project root)
php ../create_db.php

# Run migrations & seeders
php artisan migrate --seed

# Serve backend dev server
php -S localhost:8000 -t public

# Frontend dev server (separate terminal)
cd frontend
npm install
npm run dev        # localhost:3000, proxies /api -> localhost:8000

# Build frontend
npm run build

# Run tests
vendor/bin/phpunit                          # all tests
vendor/bin/phpunit tests/SomeTest.php       # single test file
vendor/bin/phpunit --filter method_name     # single test method

Architecture notes

  • Service-Repository pattern: Controllers inject Services via constructor DI; Services inject Repositories. Repository layer wraps Eloquent queries. BaseRepository provides shared CRUD.
  • Auth: Custom JWT via firebase/php-jwt (HS256). Token in Authorization: Bearer <token> header. Token expires in 24h (JWT_TTL=1440 in .env, set as time() + 86400 in code).
  • Middleware: cors (global), jwt (route: most endpoints), admin + employee (available but not used in routes currently).
  • Gates: admin = owner/admin roles; owner = owner role only.
  • CORS: Wide open (* origins, * methods, * headers) via CorsMiddleware and config/cors.php.
  • Database: MySQL bnet_bookkeeping, charset utf8mb4, timezone Asia/Jakarta.
  • API response convention: { "success": bool, "message": string, "data": ... }.
  • Helpers (auto-loaded via composer.json autoload files): formatRupiah(), generateCustomerId(), formatDate().
  • SoftDeletes on Customer model.
  • Frontend: React 19 + Vite 8, Tailwind CSS v4 (@tailwindcss/vite plugin). Design tokens from DESIGN.md applied via @theme in index.css.
  • Auth flow: Login page POSTs to /api/auth/login, stores JWT in localStorage. Axios interceptor attaches Bearer token to every request. 401 response auto-redirects to /login.
  • DESIGN.md tokens are implemented in frontend/src/index.css as Tailwind @theme variables. All UI components reference these tokens.
  • .env is gitignored; must be created from .env.example. The post-root-package-install script auto-copies it.
  • Dummy data: seed_dummy.php creates 15 customers (12 active, 1 isolated, 2 deactivated), 39 bills (3 months), 26 payments. Run cleanup.php first to reset.

Status checklist

  • Backend: Migrations + seeders (roles, users, packages, payment methods)
  • Backend: All API routes, controllers, services, repositories
  • Backend: JWT auth, middleware, gates
  • Frontend: Login page + AuthContext
  • Frontend: Reusable UI components (Button, Card, Input, Select, Badge, Modal, Table, Toast, EmptyState, Skeleton, Loading, Pagination)
  • Frontend: Layout (Sidebar, Navbar, MainLayout)
  • Frontend: All pages (Dashboard, Customers, CustomerDetail, CustomerForm, Packages, Billing, Payments, Reports, Arrears, Settings)
  • Frontend: Axios instance + JWT interceptor
  • Dummy data: 15 customers, 39 bills, 26 payments
  • Frontend: Build test (npm run build)
  • Test: Full CRUD flow on all pages
  • Test: Edge cases (empty states, error handling)