Secure payroll intelligence · 2025–2026
Payslip Agent
A payroll assistant for authenticated retrieval, explanations, tax calculations, and protected documents. Its central engineering constraint is keeping employee identity and session ownership explicit.
Role & context
- Contribution
- FastAPI assistant, streaming tool execution, MCP integration, and request/session isolation.
- Setting
- Internal payroll assistant at PeopleStrong · 2025–2026
- Public scope
- Public design summary. Employee records, protected documents, and internal endpoints are intentionally omitted.
The problem
Payroll questions sound conversational, but the underlying data is sensitive, user-specific, and calculation-heavy. Identity and session boundaries therefore matter as much as the quality of the generated answer.
A closer look
Identity belongs to a request, not a shared process
- Constraint
- Payroll questions are user-specific. A shared mutable employee context is the wrong ownership boundary when requests can overlap.
- Decision
- Khalid replaced shared user context with request-scoped employee and organization identity, alongside Redis-backed sessions with explicit expiry. Retrieval, content queries, document handling, and tax calculations remain separate tool capabilities.
- Tradeoff
- Explicit context has to be carried through each tool call instead of relying on convenient process-wide state. That additional discipline makes the data-access boundary legible.
- Evidence boundary
- Registration and session-validation contract tests cover those parts of the tool interface. This case describes identity-isolation hardening; employee data and internal test fixtures are not published.
What Khalid built
Khalid built the assistant in FastAPI with streaming responses and a tool layer for retrieval, document access, tax calculations, and explanations.
He later exposed payslip retrieval, document handling, content queries, and Indian tax calculation through four MCP tools with session validation.
Shared mutable user context was removed in favor of request-scoped identity and Redis-backed sessions with explicit expiry.
The implementation also uses decimal financial math, protected storage flows, PII-aware logging, token-usage reporting, and contract tests around registration and session validation.
Public architecture
Explore the architecture
- Employee request
A payroll question or document request starts the flow.
- Identity gate
Trusted request context determines whose data the tools are allowed to access.
- Tool layer
Small, purpose-specific capabilities handle retrieval, explanation, document delivery, and tax math.
- Payroll sources
Structured records and protected documents are accessed through controlled retrieval paths.
- Session state
Conversation state is explicit, scoped, and time-bounded.
- Response / document
The user receives an explanation, calculation, or protected document only after the trust checks are satisfied.
Public abstraction. Proprietary implementation details are omitted.
Design decisions
Identity first
Employee and organization context is derived per request rather than inherited from process-wide mutable state.
Small tool surface
Retrieval, document access, content questions, and tax calculations remain distinct capabilities.
Session lifetime
Conversation state has explicit ownership and expiry rather than living indefinitely in a server singleton.
Protected delivery
Sensitive payroll content and documents stay behind authenticated access paths.
Evidence & limits
Identity and session boundaries
Request-scoped identity, expiring sessions, decimal financial calculations, protected delivery, and PII-aware logging are concrete parts of the implementation. Contract tests cover registration and session validation. This public summary describes those controls, rather than an independent security certification.
Takeaway
The project reinforced a simple rule: when AI touches sensitive data, state management and identity handling are part of the security design.