Backend API for Kachingko - Handles credit card statement parsing, transaction categorization, and data management.
- PDF Statement Parsing — Extract transactions from RCBC and EastWest Bank statements
- Transaction Processing — Automatic categorization with machine learning
- Data Management — Secure storage and retrieval of financial data
- Budget API — Set limits and track spending across categories
- Analytics Engine — Generate spending insights and trend analysis
- RESTful API — Clean, documented endpoints for frontend integration
- Elixir — Functional programming language
- Phoenix — Web framework
- Ecto — Database wrapper and query generator
- PostgreSQL — Primary database
- PdfPlumber and PikePDF — PDF processing (via Erlport)
- RCBC
- EastWest
- BPI
- BDO
- Metrobank
We recommend using asdf to manage Elixir and Erlang versions. This ensures consistent versions across development environments.
macOS:
# Using Homebrew
brew install asdf
# Add to your shell profile (~/.zshrc or ~/.bash_profile)
echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ~/.zshrc
source ~/.zshrcUbuntu/Debian:
# Clone asdf repository
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.13.1
# Add to shell profile
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc
source ~/.bashrc# Add Erlang and Elixir plugins
asdf plugin add erlang https://github.com/asdf-vm/asdf-erlang.git
asdf plugin add elixir https://github.com/asdf-vm/asdf-elixir.git
# Install Erlang (required for Elixir)
asdf install erlang 28.0
asdf global erlang 28.0
# Install Elixir
asdf install elixir 1.18.4-otp-28
asdf global elixir 1.18.4-otp-28
# Verify installation
elixir --version# Install Phoenix framework
mix local.hex --force
mix archive.install hex phx_new --force
# Verify Phoenix installation
mix phx.new --versionThe project requires Python 3.11+ for PDF processing components.
# Add Python plugin
asdf plugin add python
# Install Python
asdf install python 3.13.0
asdf global python 3.13.0
# Verify installation
python --version
# Install required Python packages
pip install pdfplumber==0.11.6 pikepdf==9.11.0Create a .tool-versions file in your project root to lock versions:
# .tool-versions
elixir 1.18.4-otp-28
erlang 28.0Then run:
asdf install # Installs versions specified in .tool-versions- Elixir 1.18.4+
- Phoenix 1.8.1+
- PostgreSQL 14+
- Python 3.11+ (for PDF processing)
Create .env:
export DATABASE_URL=
export PORT=8888
export SECRET_KEY_BASE=
export CLOAK_KEY=
export GUARDIAN_SECRET_KEY=
# generate SECRET_KEY_BASE and GUARDIAN_SECRET_KEY
mix phx.gen.secret
# generate CLOAK_KEY for TXN details encryption
iex> :crypto.strong_rand_bytes(32) |> Base.encode64()
# Clone repository
git clone https://github.com/braynm/kachingko-api.git
cd kachingko-api
# Install dependencies
mix deps.get
# Load environment variables
source .env
# Setup database
mix ecto.setup
# Start server
mix phx.serverAPI will be available at http://localhost:8888
mix phx.server # Start Phoenix server
mix test # Run tests
mix format # Format code
mix credo # Lint code
mix phx.routes # Show all routes
mix ecto.migrate # Run database migrations
mix ecto.reset # Reset database├── application.ex
├── authentication
│ ├── application
│ ├── authentication.ex
│ ├── domain
│ └── infra
├── charts
│ ├── application
│ ├── charts.ex
│ ├── domain
│ └── infra
├── encrypted_types.ex
├── mailer.ex
├── repo.ex
├── shared
│ ├── bank_formatter.ex
│ ├── errors.ex
│ ├── pagination
│ ├── result.ex
│ └── types.ex
├── statements
│ ├── application
│ ├── domain
│ ├── infra
│ └── statements.ex
├── utils
│ ├── date_timezone.ex
│ └── validator_formatter.ex
└── vault.ex
# Create migration
mix ecto.gen.migration add_new_field
# Run migrations
mix ecto.migrate
# Rollback
mix ecto.rollback# Run all tests
mix test
# Run specific test file
mix test test/kachingko/transactions_test.exs
# Run with coverage
mix test --cover- Create parser module in
lib/kachingko_api/statements/infra/parsers/ - Implement
BankParserbehaviour - Add bank configuration to
config/config.exsinside:supported_banks - Write tests in
test/kachingko_api/statements/infra/parsers/
# Set environment
export MIX_ENV=prod
# Install dependencies and compile
mix deps.get --only prod
mix compile
# Build release
mix release
# Run release
_build/prod/rel/kachingko_api/bin/kachingko_api start- Disk Encryption: Enable FileVault (macOS), BitLocker (Windows), or LUKS (Linux) to protect database files at rest
- Database Access: Secure your PostgreSQL instance with strong passwords and network restrictions
- Backups: If backing up to cloud storage, consider encrypting dump files before upload
- Use HTTPS/TLS for all connections
- Implement network firewalls
- Regular security updates for OS and PostgreSQL
- Consider application-level encryption if handling highly sensitive data
For enterprise security features (2FA, audit trails, advanced monitoring), consider our hosted SaaS solution.
Contributions are welcome! Please read our contributing guide.
- Fork the repository
- Create your feature branch (
git checkout -b feature/new-feature) - Commit your changes (
git commit -m 'feat: add new feature') - Push to the branch (
git push origin feature/new-feature) - Open a Pull Request
- Web App: kachingko-web - Frontend application
- Docs: kachingko-docs - Documentation
This project is licensed under the Apache 2.0 - see the LICENSE file for details.
- Documentation: kachingko-docs
- Discussions: GitHub Discussions