{"id":50975618,"url":"https://github.com/christitustech/titusbooks","last_synced_at":"2026-06-23T11:01:00.244Z","repository":{"id":365277103,"uuid":"1271305945","full_name":"ChrisTitusTech/titusbooks","owner":"ChrisTitusTech","description":"I hate quickbooks, I'm making my own self-hosted all data never leaves local network.","archived":false,"fork":false,"pushed_at":"2026-06-21T23:52:56.000Z","size":300,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-06-22T10:27:59.896Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C#","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/ChrisTitusTech.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":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-16T14:31:13.000Z","updated_at":"2026-06-22T04:25:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ChrisTitusTech/titusbooks","commit_stats":null,"previous_names":["christitustech/titusbooks"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ChrisTitusTech/titusbooks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisTitusTech%2Ftitusbooks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisTitusTech%2Ftitusbooks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisTitusTech%2Ftitusbooks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisTitusTech%2Ftitusbooks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChrisTitusTech","download_url":"https://codeload.github.com/ChrisTitusTech/titusbooks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisTitusTech%2Ftitusbooks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34686726,"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":[],"created_at":"2026-06-19T07:32:34.589Z","updated_at":"2026-06-23T11:01:00.225Z","avatar_url":"https://github.com/ChrisTitusTech.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TitusBooks\n\nTitusBooks is a multi-platform bookkeeping desktop app on an Avalonia + ASP.NET Core + .NET 10 + PostgreSQL foundation.\n\nPhases 0 through 5 of the roadmap are implemented locally. TitusBooks currently supports organization and account setup, manual expense/income/transfer posting, account registers, financial reports, CSV report export, and generic CSV transaction staging with column mapping and duplicate detection.\n\n## Files\n\n- `SPEC.md` - Product, accounting, database, import, security, and UX specification.\n- `ROADMAP.md` - Phased implementation roadmap with milestones and acceptance criteria.\n- `AGENTS.md` - Codex agent operating instructions and task decomposition rules.\n- `SKILLS.md` - Domain and technical skills Codex should apply while working on the project.\n- `src/FinancialApp.Desktop` - Avalonia desktop application.\n- `src/FinancialApp.Api` - ASP.NET Core API service.\n- `src/FinancialApp.Core` - Domain and application models.\n- `src/FinancialApp.Data` - PostgreSQL data access and embedded migrations.\n- `src/FinancialApp.Migrations` - CLI for applying PostgreSQL migrations.\n- `src/FinancialApp.Importers` - Generic CSV parsing, normalization, fingerprinting, and staging services.\n- `src/FinancialApp.Reports` - Financial report calculations and CSV export.\n- `tests` - xUnit test projects.\n\n## Local Development\n\nPrerequisite:\n\n- .NET SDK 10\n\nBuild:\n\n```bash\ndotnet build TitusBooks.slnx\n```\n\nRun tests:\n\n```bash\ndotnet test TitusBooks.slnx\n```\n\nRun the desktop app:\n\n```bash\ndotnet run --project src/FinancialApp.Desktop/FinancialApp.Desktop.csproj\n```\n\nLocal, non-secret desktop overrides may be placed in `src/FinancialApp.Desktop/appsettings.Local.json`. Desktop clients should store the API endpoint, not PostgreSQL credentials.\n\nRun the API locally:\n\n```bash\ndotnet run --project src/FinancialApp.Api/FinancialApp.Api.csproj --urls http://127.0.0.1:5000\n```\n\nCheck API health:\n\n```bash\ncurl http://127.0.0.1:5000/health\ncurl http://127.0.0.1:5000/health/database\n```\n\nReport endpoints use inclusive `startDate` and `endDate` query parameters:\n\n```text\nGET /organizations/{organizationId}/reports/profit-and-loss\nGET /organizations/{organizationId}/reports/expenses-by-category\nGET /organizations/{organizationId}/reports/income-by-source\nGET /organizations/{organizationId}/reports/{reportName}/csv\n```\n\nGeneric CSV import endpoints:\n\n```text\nPOST /imports/csv/headers\nPOST /organizations/{organizationId}/imports/csv/preview\nPOST /organizations/{organizationId}/imports/csv\nGET  /organizations/{organizationId}/imports/transactions\n```\n\nCSV imports remain in staging and never post journal entries automatically.\n\n## Database Migrations\n\nThe migration CLI runs on the API/database host and accepts a PostgreSQL connection string from an argument or environment variable. Keep secrets out of committed config files.\n\nPreferred local setup:\n\n```bash\ncp .env.example .env\n```\n\nThen edit `.env` and fill in `TITUSBOOKS_CONNECTIONSTRING`. The `.env` file is ignored by git.\n\n```bash\ndotnet run --project src/FinancialApp.Migrations/FinancialApp.Migrations.csproj -- \\\n  --connection-string \"Host=localhost;Port=5432;Database=titusbooks;Username=postgres;Password=...\"\n```\n\nOr:\n\n```bash\nTITUSBOOKS_CONNECTIONSTRING=\"Host=localhost;Port=5432;Database=titusbooks;Username=postgres;Password=...\" \\\ndotnet run --project src/FinancialApp.Migrations/FinancialApp.Migrations.csproj\n```\n\nOr, after filling in `.env`:\n\n```bash\ndotnet run --project src/FinancialApp.Migrations/FinancialApp.Migrations.csproj\n```\n\nThe baseline migration creates organizations, accounts, import batches, imported transactions, journal entries, journal lines, categorization rules, and reconciliations.\n\n## Server Publish\n\nPublish the API for Linux x64:\n\n```bash\ndotnet publish src/FinancialApp.Api/FinancialApp.Api.csproj \\\n  -c Release \\\n  -r linux-x64 \\\n  --self-contained false \\\n  -o artifacts/publish/FinancialApp.Api\n```\n\nCopy the published files to the server:\n\n```bash\nrsync -av artifacts/publish/FinancialApp.Api/ titus@10.0.0.80:/opt/titusbooks/api/\n```\n\nThe server-side systemd service should set:\n\n```text\nASPNETCORE_URLS=http://10.0.0.80:5000\nTITUSBOOKS_CONNECTIONSTRING=Host=127.0.0.1;Port=5432;Database=titusbooks;Username=titus;Password=...;SSL Mode=Disable;Timeout=15;Command Timeout=120;Keepalive=30\nTITUSBOOKS_RUN_MIGRATIONS=false\n```\n\nInstall the systemd service template:\n\n```bash\nsudo cp deploy/systemd/titusbooks-api.service /etc/systemd/system/titusbooks-api.service\nsudo systemctl daemon-reload\nsudo systemctl enable titusbooks-api\nsudo systemctl start titusbooks-api\n```\n\nCheck service status and logs:\n\n```bash\nsudo systemctl status titusbooks-api\nsudo journalctl -u titusbooks-api -n 100 --no-pager\n```\n\nIf `TITUSBOOKS_RUN_MIGRATIONS=true`, the API applies embedded migrations during startup. Keep it `false` if you prefer running migrations manually with `FinancialApp.Migrations`.\n\n## Foundation Stack (Locked)\n\n- Desktop UI: Avalonia UI\n- API: ASP.NET Core\n- Language/runtime: .NET 10\n- Database: PostgreSQL\n- Data access: Npgsql + Dapper\n- Migrations: FluentMigrator or DbUp\n- Tests: xUnit\n- Packaging: platform-specific desktop packages later in roadmap\n\nThe outline in this repository is intentionally constrained to this stack to keep implementation decisions specific and consistent.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristitustech%2Ftitusbooks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchristitustech%2Ftitusbooks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristitustech%2Ftitusbooks/lists"}