AGENTIC · PORTFOLIO TRACKER
Portfolio Tracker: engineering a product end to end with an AI agent
A personal product in seven repositories: I set the requirements, Codex implements them under written rules, and by rule every substantial change starts from a spec and a work item and ends in a version decision; the API, the app and the site then ship through a tagged release.
Drafted with Claude Code from Portfolio Tracker's repositories (state of 3 July 2026) and published in a release Edgardo authorised on 16 November 2026. How this note was written.
In brief
- Portfolio Tracker is a read-only personal portfolio tracker, a personal project of mine (my statement of 16 November 2026), built across 7 active repositories, of which only the documentation one is public.
- Codex implements it under written rules: by rule, every substantial change starts as a spec and a work item, is validated in stages and records a version or an explicit no-release decision; the API, app and site workflows tag and release each new version, while a public engineering portal built with Docusaurus explains the system.
- As of 3 July 2026 the architecture repository held 13 specs, 74 work items in its English task files (57 marked done) and 8 architecture decisions; the API and the app's web version deployed only to development, and nothing here measures users or time saved.
| Product | A read-only personal portfolio tracker: it imports statements and trade confirmations, adds daily market data, computes metrics with auditable breakdowns and shows descriptive insights. It gives no advice, places no orders, moves no money and holds no assets. |
|---|---|
| Repositories | 7 active ones, coordinated from portfolio-architect; only portfolio-docs is public. A repository for shared contracts is deferred. |
| Stack | Architecture: Markdown, ADRs, and specs with plans and task lists. API: Express, TypeScript, Prisma, PostgreSQL and Zod. App: Expo, React Native, Expo Router and TanStack Query. Site: Next.js, Tailwind CSS and Cloudflare Pages. Database: SQL migrations and PowerShell scripts. Infrastructure: Docker Compose. Docs: Docusaurus. |
| Method | 13 specs, 74 work items in the English task files (57 marked Done; the Spanish companions list 2 more, both done), 8 ADRs and 12 lifecycle skills, in the architecture repository; state of 3 July 2026. |
| Versions | Architecture 0.1.0, API 0.1.22, app 0.1.28, database 0.1.0, infrastructure 0.1.0, site 0.1.5 and docs 0.1.0. Source: version-manifest.yml, last release on 3 July 2026. |
| Public links | The engineering portal, also in Spanish, the product site and the documentation repository. On 16 November 2026 both sites answered 200 (public observation); the site's configuration redirects / to its Spanish version. |
| AI at runtime | Yes, one piece: a language model served locally with Ollama answers a descriptive chat. The API filters the context by user and portfolio and blocks requests for buy or sell advice before calling it. |
| My statements | Portfolio Tracker is a personal project of mine, not client or employer work; the AI-Driven Development standard the repositories were adopting in phases is my own method; Codex is the agent that implements, and Ollama runs the product's local model. Source: my statement of 16 November 2026. |
What Portfolio Tracker is, and what it is not
Portfolio Tracker imports monthly statements and trade confirmations from a broker's PDFs, together with adjusted daily prices from a market data provider. It computes investment, net capital, income, expenses, market value and return, each with a breakdown of the rows behind the figure, and shows them in an app for Android and the web.
Its boundary is written into every repository: the product is read-only. It gives no financial advice or recommendations, executes no trades, routes no orders, moves no money and holds no assets. When a statement or a price is missing, it shows Pending or Partial instead of borrowing a value from another period.
Data rules follow suit: user, portfolio and broker account identifiers are UUIDs, a full account number is never a key nor displayed, and sensitive queries must filter by user and portfolio.
The engineering portal
The most visible piece is the engineering portal, built from the public portfolio-docs repository. It shows how the system fits together without access to the private repositories: 13 pages per language, in English and Spanish, written in Markdown with Docusaurus and illustrated with Mermaid diagrams. It covers:
- Architecture: the system overview, the repository map, the data flow, the integration points and the framework workflow.
- Security: the security overview, data handling and the compliance posture.
- Guides: getting started and the roadmap, plus a FAQ and a glossary.
The portal is built like code. A GitHub Actions workflow builds it on every pull request and publishes it to GitHub Pages from main. The Docusaurus configuration sets onBrokenLinks: 'throw', so a broken internal link fails the build instead of reaching the site. A second workflow, also on main, generates a Markdown copy of the pages and pushes it to the repository's wiki.
What it leaves out is deliberate. By its own scope statement it excludes internal runbooks, secrets, private infrastructure details and users' financial data, its own rules forbid publishing secrets, internal IPs or private URLs, and the spec that governs it allows API and integration concepts without private hostnames. Nothing synchronises it automatically with the other repositories: a public page changes through a work item, like any other change, and so it can fall behind (see what this does not prove).
Architecture in seven repositories
Each repository has one role, its own AGENTS.md with the rules an agent reads first, a changelog and a version:
portfolio-architect: the operational memory and the coordination point. Specs, work items, ADRs, skills and the version manifest, in Markdown; no product code.portfolio-api: authentication, imports, calculations, dashboard and chat, with Express, TypeScript, Prisma, PostgreSQL and Zod.portfolio-mobile: the app for Android and the web, with Expo, React Native, Expo Router, TypeScript and TanStack Query.portfolio-web: the commercial site, with Next.js, TypeScript and Tailwind CSS, exported as static pages to Cloudflare Pages. It shows demo screens and makes no calls to the API.portfolio-db: SQL migrations, a development seed and backup and restore scripts in PowerShell.portfolio-infrastructure: local orchestration with Docker Compose: PostgreSQL, the API, SonarQube, Ollama and the observability stack.portfolio-docs: the public portal, with Docusaurus.
At runtime the path is short. The app talks only to the API. The API reads and writes PostgreSQL, takes adjusted daily prices from the market data provider and calls the local model for the chat. The app touches neither the database nor the model, and the model runtime has no access to the database: the API builds the context it receives.
Durable decisions are recorded as ADRs. There are 8, all accepted:
- 0001, record architecture decisions, and 0002, infrastructure owns local orchestration (30 May 2026).
- 0003, GitHub backlog traceability; 0004, framework roadmap and exceptions; 0005, release train and versioning; 0006, quality and security gates; and 0007, documentation languages (31 May 2026).
- 0008, agent orchestration governance (4 June 2026).
The lifecycle: from a requirement to a deployed version
This is the core of the method: the AI-Driven Development standard that the repositories were adopting in phases and that, as I stated on 16 November 2026, is my own. Most steps have a lifecycle skill that the agent loads before acting.
- OWNER · REQUIREMENTI bring a need: a feature, a bug or a change to the method.
- SPECCodex classifies it and writes
spec.md(with a Spanish companion when in scope): user scenarios, success criteria, scope, product boundary and a compliance assessment. - PLAN AND WORK ITEMS
plan.mdandtasks.md: each work item gets acceptance criteria in Given/When/Then form, dependencies, a target repository and a GitHub issue, and moves toReadyonly when all of that is complete. - SPLIT BY REPOSITORYWork that spans repositories becomes one child task and one pull request per repository; the architecture repository coordinates them but does not mix their code.
- STAGED VALIDATIONThe smallest useful check while fixing, the full repository checks once stable, and local SonarQube once before the pull request when available; each repository's GitHub Actions workflow runs again on the pull request.
- VERSION DECISIONEach pull request records an unpublished SemVer target or an explicit no-release decision, opens as a draft and requests my review.
- COORDINATED RELEASEIn the API, the app and the site, after the merge into
mainthe workflow creates the version tag and the GitHub release; a companion pull request records the new version inversion-manifest.yml. - DEPLOYMENTThe new version reaches its environment: the API and the app go to development, the site to Cloudflare Pages and the portal to GitHub Pages.
- RETROSPECTIVEWhen I ask for it, a blameless retrospective turns a lesson into a written rule, through a new work item and pull request if the earlier ones are already merged.
Numbering ties it all together. A spec is NNN (for example 011), a work item is NNN-MMM (011-001) and a child task in one repository is NNN-MMM-XX (003-015-01); the branch carries the same number. A work item's status (Ready, In Progress, Active, Review, Done, Blocked or Deferred) lives in the local tasks.md; the GitHub issue only traces the pull request.
The definition of done is written too. Before a pull request is opened, the work must be validated; a user-facing feature must work end to end across infrastructure, API and interface, or the missing layer must be recorded as a Blocked or Deferred child task with its reason; and the work item is marked Done in the pull request's last commit. A parent work item is done only when its child tasks are.
Versions are coordinated through one manifest. Its header, as of 3 July 2026:
system_version: "0.1"
repos:
architecture: "0.1.0"
api: "0.1.22"
mobile: "0.1.28"
database: "0.1.0"
infrastructure: "0.1.0"
web: "0.1.5"
docs: "0.1.0"
shared: "planned"
site: "superseded-by: portfolio-web"
compatibility: "Active repos share MAJOR.MINOR during coordinated releases; PATCH may vary independently."Quality gates
All 7 repositories run a GitHub Actions workflow on pull requests to main. In the API, after installing dependencies and generating the Prisma client, the checks job runs these steps:
- name: Lint
run: npm run lint
- name: Test
run: npm test
- name: Build
run: npm run build
- name: Runtime dependency audit
run: npm run audit -- --omit=dev- Release notes come from the changelog. The API release fails if
CHANGELOG.mdhas no section for that version, and the site's pipeline rejects a pull request whose version is already tagged. - Dependencies. The API's CI audits runtime dependencies; ADR 0006 delegates alerts to Dependabot (recorded as enabled for the API), and defers license scanning and dynamic security testing.
- SonarQube, local only. Static analysis runs on SonarQube on the local development machine, and the validation script fails if the quality gate fails. By rule, hosted workflows do not assume access to that machine, so the hosted CI does not run it.
- Accessibility. The app's web build and the commercial site are scanned with axe and Playwright against WCAG 2.2 AA: critical or serious violations fail the job, and moderate or minor ones are only recorded. The JSON and HTML report is attached to each web release.
- Strict TypeScript. The API, the app and the site compile with
strictenabled.
Delivery and operation
The API shows the whole path. Once the checks pass on main, the workflow creates the SemVer tag (without republishing a version already released), a GitHub release with notes taken from the changelog and the image, tagged with the version, in GitHub's container registry. A last job, on a self-hosted runner, deploys it to the development environment: it applies the database migrations from the new image before recreating the container, stops if they fail, and waits for the container to report healthy.
The app has its own pipeline: on main it releases the Expo web export and its image, triggers an Android preview build and deploys the web version to development. Pushes to the preview branch ship as over-the-air updates on the preview channel, without a new native build. The site deploys its static export to Cloudflare Pages.
Observation stays local as well. An optional profile of portfolio-infrastructure runs an OpenTelemetry Collector that sends traces to Tempo, logs to Loki and metrics to Prometheus, all read from Grafana; by rule it exports nothing to hosted services.
The role of AI
Codex is the agent that implements (my statement of 16 November 2026), and it works under rules written for it. Each repository's AGENTS.md is its entry point; in the architecture repository, two of the workflow rules read:
- Propose a short plan before editing, keep changes small, and follow: 1 task = 1 module = 1 PR.
- Use `codex/NNN-MMM-short-slug` branches, or `codex/NNN-MMM-XX-short-slug` for repo/module child tasks.Coordination follows a written model. ADR 0008, of 4 June 2026, makes the architecture repository the Master Agent and each target repository a Sub-Agent:
The Master Agent owns requirements, specs, Work Item decomposition, dependency ordering, delegation, status aggregation, and architecture memory. Sub-Agents own implementation inside their repo, validation, repo docs, and PR artifacts.
That is a documented rule, not a record of agents running in parallel: the same AGENTS.md provides that, without sub-agent tooling, the agent documents the delegation plan, executes only the current repository's task and leaves the rest with an explicit status. The 12 lifecycle skills are files in the architecture repository, and one, portfolio-release-version, must be loaded at the start of every agent run.
Unlike the products in my other notes, this one calls a model at runtime: Ollama serves a local language model for a descriptive chat about the user's portfolio. The guarding happens in the API, before the model sees anything: it classifies the question with deterministic rules and, if it asks whether to buy, sell, hold, trade, invest or rebalance, answers with a fixed refusal, records it and does not call the model. Otherwise it builds a capped, sanitised context from the dashboard and data services, filtered by user and portfolio, and sends it to the model through a compatible API.
What I decide
By rule, the agent works inside a scope I set. These decisions stay with me:
- Requirements and scope. Analysis starts when I bring new work, and the specs write their scenarios from the project owner's point of view; the agent turns it into specs, plans and work items.
- Review of each pull request. By rule the agent opens the pull request as a draft and requests me as reviewer when GitHub allows it. The files do not record who performs each merge, and branch protection is blocked by GitHub's free plan for private repositories: the review is a rule, not a technical lock.
- Manual prerequisites. Some steps need me: stable domains, the Android signing fingerprint, secrets in each environment and tests on a physical device. The passkey sign-in spec lists them as manual prerequisites; on 3 July 2026 the development values were in place and the end-to-end validation was still blocked on unmerged changes and a test on a physical device.
What this does not prove
As of 3 July 2026:
- No store publication recorded. Android ships as internal preview builds.
- No production environment for the API or the app. The API and the app's web version deploy only to development; the database repository describes staging and production without implementing them. Only the commercial site is public.
- SonarQube is local only. The hosted CI does not run it.
- The portal lags behind the architecture repository. Its repository map still lists the public site as deferred, it does not mention
portfolio-webor the work of specs 009 to 013, and its workflow page lists 10 of the 12 skills. - Gaps visible in the files themselves. The test file named for isolation between users is a placeholder that compares a fixed string, although other route tests check that queries carry user and portfolio filters; the initial migration enables row-level security on 10 tables, but the repository defines no policies; iOS builds are intentionally inactive; and the app's 80% coverage threshold is set in Vitest, but CI runs the tests without coverage.
- No user or time-saved figures. None are given or claimed.
- Not financial advice. The product describes records; it recommends nothing.
What comes next
The pending work is already written as work items: finish the passkey sign-in (merge and deploy it, then test it on a physical device), migrate the API module by module to Clean Architecture with a Result pattern, and keep the public portal current under spec 008. If you want to talk about this way of working, get in touch.
How this note was written
This note was drafted with Claude Code from read-only copies of Portfolio Tracker's seven repositories: the latest commits of five of them are from 3 July 2026, and those of portfolio-web and portfolio-docs from 19 June 2026. Facts that are not in the repositories are marked, in the sentence or in the table at the top, as my statements of 16 November 2026 or as public observations made that day. Each statement was traced to its source before publishing. No AI model is named, and no AI tool carries a version, by this site's editorial rule.