# veeresh-11/meika_secure architecture

> Architecture diagram of the GitHub repository veeresh-11/meika_secure, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/veeresh-11/meika_secure
- Repository: https://github.com/veeresh-11/meika_secure

## Overview

#### Purpose and Entry Points
Meika Secure is a Python security/authentication platform centered on policy-driven access decisions, device trust, WebAuthn, token/grant issuance, and tamper-evident evidence. The HTTP application starts at `app/main.py`; API entry points include `app/api/auth.py`, `app/api/health.py`, and WebAuthn routing in `app/security/webauthn/routes.py`.

#### Request-to-Decision Enforcement Pipeline
Security processing is centralized around a pipeline/runtime boundary rather than API handlers directly deciding access. `app/security/pipeline.py` coordinates enforcement, `app/security/runtime/engine.py` supplies runtime execution, and `app/security/middleware.py` applies request-level integration. Decision types, precedence, failure handling, and canonicalization are defined under `app/security/decision.py`, `app/security/precedence.py`, and `app/security/canonical.py`; the design is explicitly fail-closed where evidence or prerequisite checks fail.

#### Authentication, Identity, and Session Services
API routes delegate to application services for authentication lifecycle operations: `app/services/auth_service.py`, `app/services/session_service.py`, and `app/services/credential_service.py`. WebAuthn is split into challenge, attestation, assertion, and mapping stages in `app/security/webauthn/challenge.py`, `app/security/webauthn/attestation.py`, and `app/security/webauthn/assertion.py`. Device registration and lifecycle data are represented in `app/db/device_models.py` and managed through `app/services/device_service.py`.

#### Policy, Risk, Device, and Graph Inputs
The authorization decision consumes independent evaluators behind the policy engine: `app/security/policy/engine.py`, `app/security/policy/evaluator.py`, and evaluator modules such as `app/security/policy/evaluators/device.py` and `app/security/policy/evaluators/risk.py`. Declarative policies live in `policies/authentication_policy.yaml`, `policies/device_policy.yaml`, and `policies/risk_policy.yaml`. Device posture/trust is evaluated in `app/security/device/trust_evaluator.py`; adaptive risk is calculated in `app/security/adaptive/risk_engine.py`. Relationship-aware checks are isolated in `app/security/graph/relationship_graph.py`.

#### Grants, Tokens, and Federation Boundaries
Successful decisions may produce scoped grants and tokens. Grant issuance/validation/storage are separated in `app/security/grants/issuer.py`, `app/security/grants/validator.py`, and `app/security/grants/store.py`; service-facing orchestration is in `app/services/grant_service.py`. Token construction and enforcement reside in `app/security/tokens/issuer.py` and `app/security/tokens/enforce.py`. Federation supports discovery, JWKS, JWT construction, signature verification, replay protection, and revocation through `app/security/federation/service.py`, `app/security/federation/verifier.py`, and `app/security/federation/replay_store_redis.py`.

#### Evidence, Audit, and Persistence
Authoritative decisions are coupled to append-oriented evidence generation and verification: `app/security/evidence/engine.py`, `app/security/evidence/writer.py`, and `app/security/evidence/verify.py`. Evidence supports hot/cold/replay memory tiers and PostgreSQL storage (`app/security/evidence/memory/tier.py`, `app/security/evidence/postgres_store.py`). Database models/session management are in `app/db/models.py` and `app/db/session.py`, with Alembic and SQL migrations under `alembic/env.py` and `migrations/`. Observability is non-authoritative and exported via `app/security/observability/emitter.py`, with SIEM/SOAR sinks in `app/security/observability/sinks/siem.py` and `app/security/observability/sinks/soar.py`.

#### High-Assurance Track D
`app/security/track_d/` is a distinct verification and transparency subsystem: Merkle logs (`track_d/merkle/tree.py`), consensus/quorum (`track_d/consensus/quorum_engine.py`), anchoring (`track_d/anchoring/multi_anchor_client.py`), and public verification (`track_d/public_verify/root_verifier.py`). It supports Ed25519, threshold signing, and pluggable HSM/PKCS#11 providers under `track_d/signing/`. SQLite is available for this subsystem via `track_d/storage/sqlite_backend.py`; Redis and PostgreSQL are the other explicit infrastructure integrations.

Main entry points: [`app/security/pipeline.py`](https://github.com/veeresh-11/meika_secure/blob/main/app/security/pipeline.py) (Enforcement pipeline), [`app/api/auth.py`](https://github.com/veeresh-11/meika_secure/blob/main/app/api/auth.py) (Auth and WebAuthn routes), [`app/services/auth_service.py`](https://github.com/veeresh-11/meika_secure/blob/main/app/services/auth_service.py) (Authentication service), [`app/security/evidence/engine.py`](https://github.com/veeresh-11/meika_secure/blob/main/app/security/evidence/engine.py) (Evidence engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["HTTP entry"]
  node_app["HTTP application<br/>FastAPI app<br/>[main.py]"]
  node_api["Auth and WebAuthn routes<br/>API routes<br/>[auth.py]"]
end

subgraph group_decision["Decision enforcement"]
  node_middleware["Security middleware<br/>request integration<br/>[middleware.py]"]
  node_pipeline["Enforcement pipeline<br/>security pipeline<br/>[pipeline.py]"]
  node_runtime["Runtime engine<br/>execution runtime<br/>[engine.py]"]
  node_policy["Policy engine<br/>authorization policy<br/>[engine.py]"]
  node_policy_inputs["Policy evaluators<br/>device, risk, graph<br/>[device.py]"]
  node_policies["Declarative policies<br/>policy definitions"]
end

subgraph group_identity["Identity and credentials"]
  node_auth_service["Authentication service<br/>application service<br/>[auth_service.py]"]
  node_session_service["Session service<br/>application service<br/>[session_service.py]"]
  node_webauthn["WebAuthn ceremony<br/>challenge and verification<br/>[challenge.py]"]
  node_device_service["Device service<br/>device lifecycle<br/>[device_service.py]"]
  node_device_data[("Device models<br/>persistence models<br/>[device_models.py]")]
end

subgraph group_issuance["Grants and federation"]
  node_grant_service["Grant service<br/>grant orchestration<br/>[grant_service.py]"]
  node_grants["Grant issuer and store<br/>scoped grants<br/>[issuer.py]"]
  node_tokens["Token issuer and enforcement<br/>token security<br/>[issuer.py]"]
  node_federation["Federation service<br/>federation boundary<br/>[service.py]"]
end

subgraph group_assurance["Evidence and assurance"]
  node_evidence["Evidence engine<br/>tamper-evident evidence<br/>[engine.py]"]
  node_evidence_store[("Evidence tiers and PostgreSQL<br/>evidence persistence<br/>[tier.py]")]
  node_track_d{{"Track D transparency<br/>verification subsystem"}}
  node_observability["Observability emitter<br/>non-authoritative telemetry<br/>[emitter.py]"]
end

node_app -->|"serves"| node_api
node_api -->|"delegates lifecycle"| node_auth_service
node_api -->|"routes ceremonies"| node_webauthn
node_app -->|"applies"| node_middleware
node_middleware -->|"enforces request"| node_pipeline
node_pipeline -->|"executes through"| node_runtime
node_runtime -->|"requests decision"| node_policy
node_policy -->|"evaluates inputs"| node_policy_inputs
node_policies -->|"defines rules"| node_policy
node_auth_service -->|"manages sessions"| node_session_service
node_auth_service -->|"uses credentials"| node_webauthn
node_device_service -->|"persists lifecycle"| node_device_data
node_policy_inputs -->|"consults posture"| node_device_service
node_pipeline -->|"records authoritative decision"| node_evidence
node_evidence -->|"appends and verifies"| node_evidence_store
node_evidence -->|"anchors transparency proof"| node_track_d
node_pipeline -->|"permits issuance"| node_grant_service
node_grant_service -->|"orchestrates"| node_grants
node_grants -->|"scopes token"| node_tokens
node_tokens -->|"federates"| node_federation
node_pipeline -.->|"emits telemetry"| node_observability

click node_app "https://github.com/veeresh-11/meika_secure/blob/main/app/main.py"
click node_api "https://github.com/veeresh-11/meika_secure/blob/main/app/api/auth.py"
click node_middleware "https://github.com/veeresh-11/meika_secure/blob/main/app/security/middleware.py"
click node_pipeline "https://github.com/veeresh-11/meika_secure/blob/main/app/security/pipeline.py"
click node_runtime "https://github.com/veeresh-11/meika_secure/blob/main/app/security/runtime/engine.py"
click node_policy "https://github.com/veeresh-11/meika_secure/blob/main/app/security/policy/engine.py"
click node_policy_inputs "https://github.com/veeresh-11/meika_secure/blob/main/app/security/policy/evaluators/device.py"
click node_policies "https://github.com/veeresh-11/meika_secure/blob/main/policies/authentication_policy.yaml"
click node_auth_service "https://github.com/veeresh-11/meika_secure/blob/main/app/services/auth_service.py"
click node_session_service "https://github.com/veeresh-11/meika_secure/blob/main/app/services/session_service.py"
click node_webauthn "https://github.com/veeresh-11/meika_secure/blob/main/app/security/webauthn/challenge.py"
click node_device_service "https://github.com/veeresh-11/meika_secure/blob/main/app/services/device_service.py"
click node_device_data "https://github.com/veeresh-11/meika_secure/blob/main/app/db/device_models.py"
click node_grant_service "https://github.com/veeresh-11/meika_secure/blob/main/app/services/grant_service.py"
click node_grants "https://github.com/veeresh-11/meika_secure/blob/main/app/security/grants/issuer.py"
click node_tokens "https://github.com/veeresh-11/meika_secure/blob/main/app/security/tokens/issuer.py"
click node_federation "https://github.com/veeresh-11/meika_secure/blob/main/app/security/federation/service.py"
click node_evidence "https://github.com/veeresh-11/meika_secure/blob/main/app/security/evidence/engine.py"
click node_evidence_store "https://github.com/veeresh-11/meika_secure/blob/main/app/security/evidence/memory/tier.py"
click node_observability "https://github.com/veeresh-11/meika_secure/blob/main/app/security/observability/emitter.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_api toneBlue
class node_middleware,node_pipeline,node_runtime,node_policy,node_policy_inputs,node_policies toneAmber
class node_auth_service,node_session_service,node_webauthn,node_device_service,node_device_data toneMint
class node_grant_service,node_grants,node_tokens,node_federation toneRose
class node_evidence,node_evidence_store,node_track_d,node_observability toneIndigo
```

## Components

### HTTP entry

- [HTTP application](https://github.com/veeresh-11/meika_secure/blob/main/app/main.py): FastAPI app · `app/main.py`
- [Auth and WebAuthn routes](https://github.com/veeresh-11/meika_secure/blob/main/app/api/auth.py): API routes · `app/api/auth.py`

### Decision enforcement

- [Security middleware](https://github.com/veeresh-11/meika_secure/blob/main/app/security/middleware.py): request integration · `app/security/middleware.py`
- [Enforcement pipeline](https://github.com/veeresh-11/meika_secure/blob/main/app/security/pipeline.py): security pipeline · Fail-closed decision coordination. · `app/security/pipeline.py`
- [Runtime engine](https://github.com/veeresh-11/meika_secure/blob/main/app/security/runtime/engine.py): execution runtime · `app/security/runtime/engine.py`
- [Policy engine](https://github.com/veeresh-11/meika_secure/blob/main/app/security/policy/engine.py): authorization policy · `app/security/policy/engine.py`
- [Policy evaluators](https://github.com/veeresh-11/meika_secure/blob/main/app/security/policy/evaluators/device.py): device, risk, graph · Independent device, adaptive-risk, and relationship inputs. · `app/security/policy/evaluators/device.py`
- [Declarative policies](https://github.com/veeresh-11/meika_secure/blob/main/policies/authentication_policy.yaml): policy definitions · `policies/authentication_policy.yaml`

### Identity and credentials

- [Authentication service](https://github.com/veeresh-11/meika_secure/blob/main/app/services/auth_service.py): application service · `app/services/auth_service.py`
- [Session service](https://github.com/veeresh-11/meika_secure/blob/main/app/services/session_service.py): application service · `app/services/session_service.py`
- [WebAuthn ceremony](https://github.com/veeresh-11/meika_secure/blob/main/app/security/webauthn/challenge.py): challenge and verification · Challenge, attestation, assertion, and credential mapping flow. · `app/security/webauthn/challenge.py`
- [Device service](https://github.com/veeresh-11/meika_secure/blob/main/app/services/device_service.py): device lifecycle · `app/services/device_service.py`
- [Device models](https://github.com/veeresh-11/meika_secure/blob/main/app/db/device_models.py): persistence models · `app/db/device_models.py`

### Grants and federation

- [Grant service](https://github.com/veeresh-11/meika_secure/blob/main/app/services/grant_service.py): grant orchestration · `app/services/grant_service.py`
- [Grant issuer and store](https://github.com/veeresh-11/meika_secure/blob/main/app/security/grants/issuer.py): scoped grants · Issues, validates, and stores scoped grants. · `app/security/grants/issuer.py`
- [Token issuer and enforcement](https://github.com/veeresh-11/meika_secure/blob/main/app/security/tokens/issuer.py): token security · `app/security/tokens/issuer.py`
- [Federation service](https://github.com/veeresh-11/meika_secure/blob/main/app/security/federation/service.py): federation boundary · Discovery, JWT verification, replay protection, and revocation. · `app/security/federation/service.py`

### Evidence and assurance

- [Evidence engine](https://github.com/veeresh-11/meika_secure/blob/main/app/security/evidence/engine.py): tamper-evident evidence · Authoritative decisions append verifiable evidence. · `app/security/evidence/engine.py`
- [Evidence tiers and PostgreSQL](https://github.com/veeresh-11/meika_secure/blob/main/app/security/evidence/memory/tier.py): evidence persistence · Hot/cold/replay memory tiers with PostgreSQL storage. · `app/security/evidence/memory/tier.py`
- **Track D transparency**: verification subsystem · Merkle, quorum, anchoring, and public root verification.
- [Observability emitter](https://github.com/veeresh-11/meika_secure/blob/main/app/security/observability/emitter.py): non-authoritative telemetry · Exports events to SIEM and SOAR sinks. · `app/security/observability/emitter.py`

## Connections

- HTTP application → Auth and WebAuthn routes: serves
- Auth and WebAuthn routes → Authentication service: delegates lifecycle
- Auth and WebAuthn routes → WebAuthn ceremony: routes ceremonies
- HTTP application → Security middleware: applies
- Security middleware → Enforcement pipeline: enforces request
- Enforcement pipeline → Runtime engine: executes through
- Runtime engine → Policy engine: requests decision
- Policy engine → Policy evaluators: evaluates inputs
- Declarative policies → Policy engine: defines rules
- Authentication service → Session service: manages sessions
- Authentication service → WebAuthn ceremony: uses credentials
- Device service → Device models: persists lifecycle
- Policy evaluators → Device service: consults posture
- Enforcement pipeline → Evidence engine: records authoritative decision
- Evidence engine → Evidence tiers and PostgreSQL: appends and verifies
- Evidence engine → Track D transparency: anchors transparency proof
- Enforcement pipeline → Grant service: permits issuance
- Grant service → Grant issuer and store: orchestrates
- Grant issuer and store → Token issuer and enforcement: scopes token
- Token issuer and enforcement → Federation service: federates
- Enforcement pipeline → Observability emitter: emits telemetry · Telemetry is not authoritative.