Skip to content
Project Planner

Architecture & data flow

Graphs generated from the project, not drawn by hand

Project Planner keeps architecture as data: components with types, technologies, dependencies, inputs, outputs and owners; flows with data types, classification and encryption. The System Map and Data Flow screens render that data — so when the project changes, the diagrams change with it.

System map

Components and dependencies

Fifteen components of the demo project across nine sections. Selecting the Sync API highlights its dependencies and the components that use it; the inspector shows technology, inputs, outputs, requirements and owner.
Project Planner—Atlas Field ServiceDemo
Atlas Field Service PlanningD

System Map

Preview — demo project content
SystemFrontendBackendDatabaseAIAPIsInfrastructure
AI provider gatewayai · plannedPostgreSQLdatabase · implementedMaps & travel timeexternal · plannedSMS gatewayexternal · plannedEvent businfrastructure · plannedOn-device storestorage · in progressAuthenticationauthentication · in progressDomain servicesbackend · in progressNotification workerbackend · plannedSync logdatabase · implementedRouting agentai · plannedCore REST APIapis · in progressSync APIapis · plannedDispatcher web consolefrontend · plannedTechnician mobile appfrontend · in progress
CMP-001Technician mobile appIn progress

Frontend · React Native

Offline-first client used by technicians in the field.

CMP-002Dispatcher web consolePlanned

Frontend · React

Map-centric console for assigning and rescheduling jobs.

CMP-003On-device storeIn progress

Storage · SQLite

Encrypted local cache of assigned work orders and pending changes.

CMP-004Sync APIPlanned

APIs · Node.js · Fastify

Delta endpoints with cursor pagination and conflict merge.

CMP-005Core REST APIIn progress

APIs · Node.js · Fastify

Work orders, customers, technicians and schedules.

CMP-006Domain servicesIn progress

Backend · TypeScript

Business rules for scheduling, status transitions and validation.

CMP-007Routing agentPlanned

AI · Provider abstraction

Proposes daily routes; suggestions are reviewed by dispatchers before applying.

CMP-008AI provider gatewayPlanned

AI · OpenAI / Anthropic compatible

Selects model and provider, tracks tokens and cost, applies fallbacks.

CMP-009PostgreSQLImplemented

Database · PostgreSQL 16

System of record with row-level security per tenant.

CMP-010Sync logImplemented

Database · PostgreSQL table

Append-only change log used to compute deltas and resolve conflicts.

CMP-011AuthenticationIn progress

Authentication · OIDC · short-lived tokens

Sign-in, device binding and role claims.

CMP-012Event busPlanned

Infrastructure · Redis Streams

Publishes domain events to notifications and sync.

CMP-013Notification workerPlanned

Backend · Node.js worker

Sends arrival notifications by SMS and push.

CMP-014SMS gatewayPlanned

External services · External service

Third-party messaging provider.

CMP-015Maps & travel timePlanned

External services · External service

Geocoding, tiles and travel-time matrix.

Data flow

How data moves — and what kind of data it is

User → Interface → Application logic → AI and services → Database → External services → Result. Every edge in the demo project carries a data type and a classification, which is exactly what the Security Agent audits.
Project Planner—Atlas Field ServiceDemo
Atlas Field Service PlanningD

Data Flow

Preview — demo project content
All dataPersonalInternalCredentialShow external services · Show infrastructure
Status, photos, s…Change recordsChange batch + cu…CommandsRows + sync logDelta batchOpen jobs (anonym…Structured promptRoute proposalProposals + confi…Arrival eventTechnicianuserAI providerexternalMobile appinterfaceDomain serviceslogicPostgreSQLdatabaseCustomer notificationexternalPending change queuelogicRouting agentaiSync APIserviceDispatcher consoleresult
FromToDataClassificationEncrypted
TechnicianMobile appStatus, photos, signatureHighpersonalYes
Mobile appPending change queueChange recordsHighpersonalYes
Pending change queueSync APIChange batch + cursorHighpersonalYes
Sync APIDomain servicesCommandsLowinternalYes
Domain servicesPostgreSQLRows + sync logHighpersonalYes
PostgreSQLSync APIDelta batchHighpersonalYes
PostgreSQLRouting agentOpen jobs (anonymised)LowinternalYes
Routing agentAI providerStructured promptLowinternalYes
AI providerRouting agentRoute proposalLowinternalYes
Routing agentDispatcher consoleProposals + confidenceLowinternalYes
Domain servicesCustomer notificationArrival eventHighpersonalYes

Decision records

Why the architecture looks the way it does

Architecture decision records keep the reasoning next to the result. The demo project records five.
  1. ADR-001Offline-first mobile client with local SQLite store2026-08-21Accepted
  2. ADR-002PostgreSQL with row-level security per tenant2026-08-26Accepted
  3. ADR-003Provider-agnostic AI gateway; no vendor lock-in in agents2026-09-02Accepted
  4. ADR-004Append-only sync log for conflict resolution2026-09-20Accepted
  5. ADR-005Route proposals require dispatcher approval before applying2026-09-20Proposed

The application itself

How the Windows application is structured

Project Planner is built in clearly separated layers so that a future web edition can share the domain model and design system while the desktop layer stays isolated behind a platform abstraction.
  1. 01

    UI

    Application shell (sidebar, workspace, inspector), design system, screens. Consumes typed view models only.

  2. 02

    Domain

    Project, Requirement, Phase, Milestone, Task, ArchitectureComponent, DataFlowNode/Edge, Agent, AgentRun, MCPServer, Skill, Memory, Artifact, Decision, Audit, Test, Provider, Environment, GitState, Export.

  3. 03

    Application services

    Project creation and import, planning, traceability, graph building, blueprint and export generation, audits, event bus.

  4. 04

    AI

    Provider abstraction (OpenAI, Anthropic, Google, DeepSeek, compatible), model selection and fallback, cost tracking, agent runtime, skills, MCP client.

  5. 05

    Visualization

    Graph model, layered layout, filtering, grouping, highlighting, inspector integration.

  6. 06

    Infrastructure & integrations

    Local project storage, file system, file watcher, terminal (PowerShell, cmd, WSL), Git, environment detection, native notifications.

  7. 07

    Security

    Path validation, secret redaction, permission model for MCP, providers and command execution, encrypted local credential storage, audit records.

Project identity: the .pp file

Every Project Planner-managed project carries a plain-text .pp file in its root. It tells humans and AI development tools to read the planning directory first — identity, requirements, architecture, development instructions, agent instructions, skills, MCP configuration, memory, constraints, security, testing and deployment requirements — before acting.

# Project Planner identity file
version = 1
project = Atlas Field Service
project_type = saas
planner_folder = ./project-planner
schema_version = 1
created_at = 2026-08-14

Planning directory

Planning documentation lives beside the application source, never inside it.

ProjectRoot/
├── .pp
├── application/
└── project-planner/
    ├── README.md
    ├── project-identity/   ├── requirements/
    ├── architecture/       ├── data-flow/
    ├── ui-ux/              ├── agents/
    ├── skills/             ├── mcp/
    ├── memory/             ├── development/
    ├── testing/            ├── security/
    ├── compliance/         ├── deployment/
    ├── decisions/          ├── changelog/
    ├── artifacts/          ├── presentations/
    └── blueprint/
Diagrams and tables on this page are rendered from demo project content and illustrate planned behaviour of the Windows application.
Feedback