PortfolioDesk for agency IT

1. Overview and architecture

PortfolioDesk holds three linked layers: an intake queue where requests are captured and scored, a project record that tracks budget, schedule, and risk over time, and a reporting layer that rolls projects up into portfolio, executive, and board views. Data enters by file import or API, is validated on the way in, and every roll-up traces back to the underlying project records.

Integration is deliberately file-based first: data is exchanged as CSV files over SFTP or secure upload, with API connectors available where a source system exposes one. PortfolioDesk does not require a live API from your finance system, ticketing tool, or reporting stack. Many agency systems cannot expose a stable, permissioned API, so PortfolioDesk treats API access as an enhancement, not a requirement. Nothing in your stack is replaced.

  SOURCE SYSTEMS                         PORTFOLIODESK
  spreadsheets / ticketing / finance ERP / BI
        |  CSV upload or SFTP, or API pull       |
        +-------------------+--------------------+
                            v
                 IMPORT + VALIDATION            schema, types, referential checks
                            v
        +----------- INTAKE QUEUE -----------+   requests scored on your criteria
        |                                    |
        v                                    v
   PROJECT RECORDS                     PRIORITIZED BACKLOG
   budget / schedule / risk / updates        |
        |                                     |
        +------------------+------------------+
                           v
                    AI ASSIST (drafts)         status summaries, risk flags, report sections
                           v  (human review + approve)
                REPORTING / DASHBOARDS / BOARD PACKET / AUDIT LOG

The AI layer only ever produces drafts. It reads project data and proposes a status summary, a risk flag, or a report section; a named person reviews and approves before it enters a report or a decision. PortfolioDesk never posts to your finance system and never changes a project record on its own.

2. Data import model

Transport and encryption

Data enters PortfolioDesk three ways: secure web upload for ad-hoc spreadsheets, SFTP for scheduled file drops, and API connectors for systems that support them. SFTP is over SSH only; FTP/FTPS and plain SCP are not accepted, and authentication is per-account SSH key pair with password auth disabled by default. Transport is TLS 1.2+ for web and API. Optional source-IP allow-listing per account.

/in/          files you push to PortfolioDesk
/in/archive/  processed files moved here after import
/reject/      files that failed validation, with a paired .error.txt

Cadence

Imports are batch-oriented and configurable per source: on demand for uploads, and scheduled (default nightly) for SFTP and API feeds. The /in directory is polled on a configurable interval (default 15 min) and a file is only imported once its paired manifest is present, so a partially uploaded file is never processed.

File naming and CSV conventions

<source>_<agency>_<feed>_<YYYYMMDD>_<HHMMSS>_<seq>.csv
<source>_<agency>_<feed>_<YYYYMMDD>_<HHMMSS>_<seq>.manifest.json

example: finance_agcy_actuals_20260824_020115_001.csv

• Encoding UTF-8 no BOM. Delimiter comma, RFC 4180 quoting. LF or CRLF.
• Header row required; columns mapped by name, so order is not significant and unknown columns are ignored and logged.
• Dates ISO 8601 YYYY-MM-DD. Money is decimal, no separators or symbols. Identifiers are opaque strings, so leading zeros are preserved.

Control manifest

Every scheduled data file ships with a JSON manifest. A file whose manifest is missing, whose row count disagrees, or whose checksum fails is moved to /reject and never imported.

{
  "schema_version": "1.0",
  "feed": "actuals",
  "source_id": "finance",
  "agency_code": "agcy",
  "data_file": "finance_agcy_actuals_20260824_020115_001.csv",
  "generated_at": "2026-08-24T02:01:15-05:00",
  "row_count": 312,
  "sha256_plaintext": "9f2c4b...e11a",
  "period_start": "2026-08-01",
  "period_end": "2026-08-31"
}

3. Import specifications

Four feeds drive the portfolio. The engine joins them on a small set of shared keys: project_id, agency_code, and period.

3.1 Project master feed=project

One row per project. The record every other feed attaches to.

project_id,name,sponsor,phase,fund_source,budget,baseline_start,baseline_end
PRJ-0442,Public portal rebuild,CIO office,execution,operating,1850000,2026-01-06,2026-11-30
PRJ-0451,Facilities HVAC capital,Facilities,design,capital,4200000,2026-03-02,2027-08-15
PRJ-0460,ERP finance module,Enterprise systems,execution,bond,3100000,2025-10-01,2026-12-20

3.2 Actuals feed feed=actuals

One row per project per period, from your finance or ERP system. The "what has been spent" side that drives budget variance. Key fields: project_id, period, spend_to_date, and optional committed for open encumbrances.

3.3 Schedule feed feed=schedule

One row per project milestone: the "what is due and what is done" side. Carries milestone_id, planned_date, actual_date, and status (not_started / in_progress / complete / slipped), which drives schedule variance and at-risk detection.

project_id,milestone_id,name,planned_date,actual_date,status
PRJ-0442,M3,Accessibility review,2026-07-15,,slipped
PRJ-0442,M4,Vendor UAT,2026-08-30,,in_progress
PRJ-0460,M6,Go-live,2026-12-20,,in_progress

3.4 Risk feed feed=risk

Optional feed of logged risks per project: risk_id, project_id, description, likelihood (1-5), impact (1-5), and status. Risks can also be entered directly in the app; the feed is for agencies that already keep a risk register elsewhere.

4. Scoring and roll-up

Intake scoring

Incoming requests are scored on criteria you define, each with a weight. A default model ships with five criteria, and you adjust the set and weights to your agency's priorities.

Health classification

Each active project is classified deterministically from its variance and open risks, and the rule and values are logged so staff see why a project is flagged, not just that it is.

Thresholds are configurable per agency and per fund source. Roll-ups aggregate project health into portfolio, department, and fund-source views, and every figure in an executive or board report traces to the project records behind it.

5. AI assist and controls

The AI is assistive and human-in-the-loop. It has four jobs, and none of them change a record or a decision on their own.

• Status summaries. Reads a project's updates, budget, and schedule and drafts a plain-language status paragraph for a human to edit and approve.
• At-risk detection. Applies the deterministic health rules continuously and surfaces trending-worse projects early, with the triggering values attached.
• Scenario comparison. Estimates the portfolio-level budget and capacity effect of deferring, cutting, or accelerating a project, to inform a human decision.
• Report-section drafting. Assembles recurring executive and board sections from live portfolio data as a draft to review.

6. Security and data integrity

The controls below describe the system's design. Where language says "designed to," it reflects control intent and implementation, not a completed third-party audit or a specific certification, which is not claimed here.

Data minimization

PortfolioDesk tracks projects, budgets, schedules, and risks, not individuals. The feeds carry project, financial, schedule, and risk data. Personal data about the public is not required and should not be sent. Unmapped columns are ignored and not persisted into the portfolio store.

Encryption and access

• In transit: TLS 1.2+ for web and API; SFTP over SSH for scheduled file drops.
• At rest: data stores and backups designed to be AES-256 encrypted; keys held in a managed secrets store.
• RBAC: least-privilege roles (Viewer, Intake analyst, Project manager, Approver, Executive, Auditor). Designed to support SSO via SAML 2.0 / OIDC with MFA at your IdP. Access is scoped to a single agency; no cross-agency visibility.
• Immutable audit log: every import, intake score, health classification (with the rule and values behind it), status approval, human action, and report export is written to an append-only, hash-chained log. The Auditor role can read it; no role can edit or delete it through the application.

Data privacy

Designed to operate as a service provider under an agency data-processing agreement, handling only the data needed for portfolio management, under the agency's direction, never for any secondary purpose, advertising, or model training. PortfolioDesk executes an agency-provided DPA and applicable addenda. This is design and contractual intent, not a claim of a completed audit or certification.

7. Implementation and onboarding

A typical agency goes from kickoff to go-live in roughly 4 to 8 weeks, gated mainly by how quickly you can produce your current project trackers and confirm scoring criteria.

• Discovery and field mapping (wk 1). Map your project trackers and finance export to the PortfolioDesk schema; agree scoring criteria and health thresholds; confirm DPA scope.
• Provisioning (wk 1-2). Accounts, SSO, SFTP or API connectors, an end-to-end test import.
• Import and validation (wk 2-3). Your real project data validated for encoding, types, and referential integrity, then loaded so the live portfolio is in the tool.
• Configuration (wk 3-5). Dashboards, report views, and roles set up; AI status summaries tuned against your real projects with a human approving.
• Go-live (wk 5+). The portfolio dashboard becomes the working view and the first executive or board report is produced from it.

8. IT FAQ

Do you need write access to our finance or ERP system?

No. PortfolioDesk never writes to your finance system and needs no credentials to it. It imports an actuals extract on a schedule and computes variance inside PortfolioDesk under your controls.

Where is our data hosted?

A managed cloud environment with encryption at rest and logically isolated per-agency data. Single-tenant or agency-specified region deployment is available; the hosting model, region, and subprocessors are documented in the DPA.

Can we start from spreadsheets only?

Yes, and most agencies do. A CSV upload of your current project tracker is enough to stand up a live portfolio. Finance, ticketing, and BI connectors are added afterward where they help.

What if our file format differs from your examples?

Expected and handled. PortfolioDesk maps by header name against a field mapping agreed during discovery, so your column names, order, and extra columns are accommodated without changing your export.

Is the AI ever making changes on its own?

No. Every AI output is a draft that a named person reviews and approves. The AI does not change project records, scores, or reports autonomously, and every approval is logged.

Can we run single-tenant?

Single-tenant hosting is a standard option where policy requires it. The file-based architecture keeps the external surface small, which makes an isolated deployment practical.

What happens to our data at contract end?

You receive a full export of your data (project records, imports, audit log) in a documented format. After the export is confirmed, PortfolioDesk securely disposes of your data on a defined schedule and records a disposal confirmation in the audit log.