> For the complete documentation index, see [llms.txt](https://cuesoft.gitbook.io/expendit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cuesoft.gitbook.io/expendit/overview.md).

# Overview

Expendit is an open-source expense-tracking application — record expenses, categorize them, import statements, and generate real-time reports. This document describes the high-level architecture and each component's responsibilities. To run the stack locally, see [setup.md](/expendit/setup.md).

## Architecture

```mermaid
flowchart LR
    WEB[Next.js web app<br/>web/] -->|HTTPS REST| API[Go REST API — Gin<br/>api/common/]
    MOB[Flutter mobile<br/>mobile/, planned] --> API
    API --> MG[(MongoDB)]
    API --> RD[(Redis<br/>rate limits)]
    API --> GAUTH[Google OAuth]
    API --> AI[AI extraction/categorization<br/>Vertex in cloud · BYO keys self-host]
    API --> SMTP[SMTP email]
```

* **`web`** — Next.js marketing site + authenticated dashboard (React, TypeScript). Talks to the API over HTTP (REST).
* **`mobile`** — Flutter app + native shells (`mobile/{flutter,android,ios}`), placeholders today, consuming the same API.
* **`api/common`** — Go service (module `github.com/cuesoftinc/expendit/api/common`, Gin): the source of truth for auth/users, expenses/income/categories, statement imports (CSV/PDF parsing, dedup, categorization), AI-assisted summaries (Gemini/Groq), and reporting.
* **Auth** — JWT (`golang-jwt`) plus Google OAuth.
* **Data** — MongoDB (records); Redis for rate limiting (in-memory fallback).

Backend services are named by **function**, never by language: the current service is `api/common`; a future one would be `api/<function>`. See the [repository structure](https://github.com/cuesoftinc/expendit#repository-structure) in the README.

## Product & design documentation

> Published site: **<https://cuesoft.gitbook.io/expendit>** (Git-synced from this folder on every merge to main).

* [prd.md](/expendit/product/prd.md) — product requirements breakdown (requirements vs current state, user rights, open questions)
* [architecture.md](/expendit/system/architecture.md) — system design, import-pipeline deep dive, target sequences
* [data-model.md](/expendit/system/data-model.md) — current + target entities, identity migration, data classification
* [api.md](/expendit/system/api.md) — full current surface and v1 deltas with gap analysis
* [roadmap.md](/expendit/product/roadmap.md) — phased plan with dependencies
* [design.md](/expendit/design/design.md) + [pages.md](/expendit/design/pages.md) — design language, screens, microinteractions
* [line-items.md](/expendit/system/line-items.md) — canonical statement vocabulary + ratio formula registry
* [decisions.md](/expendit/product/decisions.md) — the ratified decision register (governs all docs)
* [deployment.md](/expendit/system/deployment.md) — Cloud Run + App Hosting contract (cuesoft-iac provisioning, CI/CD pattern)
* flows/ — feature flow specs with edge cases: [auth](/expendit/flows/auth.md), [import](/expendit/flows/import.md), [bank-link](/expendit/flows/bank-link.md)
* [tax-engine.md](/expendit/system/tax-engine.md) — NG PIT/CIT/VAT computation contract (versioned rule sets, trace requirements)
* [engineering.md](/expendit/system/engineering.md) — error catalog, authz matrix, rate limits, testing strategy, logging rules
* [features.md](/expendit/product/features.md) — granular build backlog (stable unit IDs per phase)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cuesoft.gitbook.io/expendit/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.