Persistent Service Examples and Template

This guide is for developers who are new to persistent-service-examples and persistent-service-template. It explains what the repository is for, when to use it, and how to work with it.

The Persistent Service is implemented as the connector codebase and the local File Manager stand-in is the fm-proxy service used only on developer machines.

What Is the Examples Repository?

persistent-service-examples is a cookbook-style repository. It shows many ways to build APIs on the same Dais stack used by a Persistent Service: background jobs, SQLite, File Manager integration, optimization, document generation, GenAI-style flows, and more. Everything lives in one place so you can read working code and copy patterns that match your App.

How It Differs From the Template

Concept	Template	Examples
Role	A starting point: a small, focused Persistent Service you extend yourself.	A reference library: many finished mini-features that share one server.
Scope	Minimal surface area; optional path for a full UI in-repo alongside the backend.	Backend-first breadth of API patterns; not centered on a bundled UI Builder workflow in this repo.
Learning curve	“Here is the engine; you add the car.”	“Here are several cars; strip yours down to what you need.”

What Problem It Solves

• “How do I actually do X on this stack?” — Examples answer with runnable patterns (outbound HTTPS in Dais, optimizers, documents, and similar).
• “What does production-ish setup look like?” — Including deployment variants (with vs without broad internet access) and optional commercial tooling wired through environment and startup behavior.
• Decision fatigue on the template — The template stays small on purpose; examples show concrete integrations so you are not inventing everything from first principles.

When Should You Use It?

Scenarios Where Examples Fit Well

• You need patterns, not just an empty shell: GenAI-style flows, scheduling or optimization demos, export or reporting, travel or weather-backed APIs, and similar.
• You are deploying to Dais and need clarity on internet access, secrets, and capabilities (for example outbound HTTPS) for APIs that call third parties.
• You want one repository to search and learn from before you carve out a smaller Persistent Service for production.

When to Prefer the Template Instead

• You want the smallest possible Persistent Service and will add only what you need.
• You follow source-controlled UI Builder assets and backend in a single repository and want that workflow documented and scaffolded (see the template’s own README).
• You want to avoid pulling in heavy optional dependencies (solvers, ML stacks, document tooling, and similar) that the examples may include for demos.

How to Use It Effectively

High-Level Workflow

1. Run the Persistent Service and the local File Manager stand-in so file-related APIs behave as they would against Dais File Manager.
2. Pick one or two examples that resemble your feature; read the README for that area and exercise the APIs.
3. Choose a deployment posture for Dais: decide whether your Persistent Service needs general internet access or can run under a stricter posture; align your deployment manifest and secrets accordingly.
4. Copy patterns, not the whole tree: lift route module structure, dependency choices, and environment or secrets handling into your own layout.
5. Register only what you ship: the running app should expose your routers and lifecycle hooks, not every demo route.

Where to Plug In Your Logic

Think in layers:

• HTTP surface — New capabilities are FastAPI routers grouped by domain. You add endpoints and wire them into the application the same way the demos do conceptually.
• Startup and shutdown — For caches, clients, or background resources, use the app lifespan pattern: nest small async context managers that initialize on startup and clean up on shutdown.
• Long-running work — Use the existing background task and ETL patterns when work should outlive a single request without blocking the server.
• Files — When user files live in Dais project storage, use the abstractions and endpoints that talk to File Manager (or the local stand-in), not ad hoc local paths only.

Key Components

Component	Responsibility
Persistent Service (connector)	Your product API: authentication boundaries as you add them, business logic, Dais SDK integration, SQLite or other stores you configure, background work.
File Manager stand-in (local only)	Development convenience: simulates Dais File Manager so list, read, and write flows work without a full cluster.
Data and volumes	Local folders for caches and File Manager simulation; in Dais, persistence is configured on the platform, but the idea is the same: where blobs and artifacts go.
Deployment manifests	How the Persistent Service image is built and published for Dais, including optional platform capabilities when your APIs need them.

Key differenced with Template

Capabilities You Can Study and Reuse

• External integrations — Patterns for outbound HTTPS and API keys (weather, LLM providers, and similar), mapped to secrets in Dais rather than hard-coding.
• Heavier domains — Optimization, document generation, and structured demos so you see end-to-end request shapes and data flow, not only CRUD-style samples.
• Deployment variants — A documented split between “needs internet from the Persistent Service” and “can run without it” so teams can match org policy and Dais approval without guessing.

Patterns and Abstractions

• Feature modules — Each major example is a cohesive package (routes, logic, README), which scales better than one giant module as your team grows.
• Shared helpers — Cross-cutting utilities (tabular parsing, timing, and similar) live in a small shared layer so demos stay readable.
• Startup hooks — Shows how to attach app-scoped state (models, caches, clients) in a structured way instead of ad hoc globals.

Mental Model

Dais UI (or API client)
        │
        ▼
   Persistent Service (connector)
   ├── Your routers and business logic
   ├── Optional SQLite or disk cache
   ├── Background job orchestration
   └── Dais SDK (File Manager, errors, conventions)
        │
        ├── Local dev: talks to File Manager stand-in
        └── Dais: talks to File Manager, secrets, and platform networking rules

How to Think About Requests

1. Ingress — HTTP reaches the Persistent Service; middlewares handle logging and consistent error shaping.
2. Domain logic — Your code validates input, calls SDKs or databases, returns Dais-friendly payloads.
3. Files — Anything that lives in the project in Dais follows File Manager semantics; locally, the stand-in replaces hand-built HTTP mocks.

Two Environments, One Codebase

• Local — Docker Compose (or equivalent) runs the Persistent Service and the stand-in; environment variables mirror secrets or configuration you will set in Dais where applicable.
• Dais — The same image idea; networking and secrets are platform-managed. Always ask whether a call needs internet, secrets, or only internal Dais services.

Scenarios in Dais store inputs and model results for a decision; your Persistent Service APIs typically read or write project files and data through File Manager and your chosen stores, aligned with how the App is structured in UI Builder.

Best Practices

Extending and Modifying

• Start narrow — Add one router package and one lifecycle concern at a time; prove it in tests before layering more.
• Align dependencies with shipped features — Each heavy library (solver, cloud SDK, LLM client) should justify its place in the image and licensing.
• Secrets — Treat .env as local-only; in Dais, use documented secret mechanisms and document required keys in your team runbook.
• Strip demos early — When you fork for production, remove unused examples and data artifacts to shrink the image and reduce confusion.

Common Pitfalls

• Leaving every demo enabled — Unused endpoints, harder security reviews, and unnecessary packages in the image.
• Ignoring internet or capability requirements — If your code calls the public internet from the Persistent Service, your deployment manifest and approvals must match; otherwise you see timeouts or opaque failures.
• Confusing local stand-in with production — Use the same File Manager abstractions in both environments; avoid hard-coding stand-in URLs in logic that runs in Dais.
• Over-copying — Prefer one reference example closest to your problem, then generalize; avoid merging unrelated patterns into one route module.