# datil/facephi-service architecture

> Architecture diagram of the GitHub repository datil/facephi-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/datil/facephi-service
- Repository: https://github.com/datil/facephi-service

## Overview

1. **What this system is**
   - `facephi-service` is a JVM/Clojure authentication service that validates users with the FacePhi biometric SDK.
   - It sits between clients that call the service and two external dependencies: the FacePhi libraries and an Oracle database.

2. **Top-level runtime and deployment shape**
   - The service runs on Java 8 and is packaged for both local execution and WAR deployment.
   - `web.xml` and `weblogic.xml` indicate servlet-container deployment, specifically targeting WebLogic 12+.
   - `deploy.sh` builds the WAR artifact, while `lein run-dev` supports local development with code reload.

3. **HTTP/service boundary**
   - `src/facephi_service/server.clj` and `src/facephi_service/service.clj` are the entry points for the request-handling layer.
   - This layer is the external API boundary: it receives client requests, routes them to domain logic, and returns structured responses.
   - The generated documentation under `doc/` suggests the service exposes multiple documented endpoints or resources.

4. **Biometric integration boundary**
   - `src/facephi_service/facephi.clj` is the adapter to the FacePhi SDK.
   - It is the primary integration point with the biometric engine, isolating SDK-specific calls from the rest of the application.
   - The README shows the build expects vendor JARs for FacePhi licensing and matcher components to be installed locally before packaging.

5. **Persistence layer**
   - `src/facephi_service/database.clj` is the database access boundary.
   - `src/facephi_service/sql/*.sql` contains SQL per aggregate/operation, including API keys, user accounts, user blocks, and user logs.
   - `resources/database.up.sql` provides schema/bootstrap SQL, implying the service manages its own schema migration or initial provisioning.

6. **Core domain areas**
   - `api_key.clj` handles API key lifecycle or validation, likely used to authenticate callers of the service.
   - `block.clj` suggests logic for blocking users or sessions, probably as an account-control or abuse-prevention feature.
   - `admin.clj` likely provides privileged operations for operators, such as managing users, blocks, or keys.
   - These modules form the business layer above persistence and below the HTTP API.

7. **Configuration and environment**
   - `src/facephi_service/conf.clj` and `config/config.edn.sample` define runtime configuration.
   - `config/logback.xml` controls logging.
   - This separation indicates the application reads environment-specific settings at startup rather than hardcoding deployment details.

8. **Cross-cutting response/message handling**
   - `src/facephi_service/messages.clj` centralizes application messages or error/result formatting.
   - That module likely standardizes response payloads and keeps user-facing text or error codes consistent across the service.

9. **Test and stub infrastructure**
   - `src/facephi_service/test_datasource.clj` and `test/facephi_service/service_test.clj` show a testable boundary around persistence and service behavior.
   - The presence of a dedicated test datasource indicates tests can run without the production Oracle connection, using a controlled substitute.

10. **Data flow through the system**
   - A typical request path is: client call → server/service layer → API key or admin checks → FacePhi SDK adapter for biometric validation → database reads/writes for user/account/block/log state → response/message formatting.
   - The database is not just storage; it also records operational history via `user_log` and enforces state such as accounts and blocks.
   - This makes the architecture a thin HTTP front end over a domain service with strong external dependencies on both biometric SDKs and Oracle.

11. **Operational and packaging constraints**
   - The project depends on locally installed vendor JARs for FacePhi and Oracle JDBC before WAR creation.
   - That makes the build partially environment-dependent: source code is in the repo, but some runtime libraries are externally sourced and installed into the local Maven repository.
   - For diagram purposes, treat those as external binary dependencies rather than repository-managed modules.

12. **Documentation footprint**
   - The `doc/` folder contains generated API/module documentation for the codebase.
   - This is useful for understanding internal module boundaries, but it is not part of the runtime path.

Main entry points: [`src/facephi_service/database.clj`](https://github.com/datil/facephi-service/blob/master/src/facephi_service/database.clj) (Database), [`src/facephi_service/service.clj`](https://github.com/datil/facephi-service/blob/master/src/facephi_service/service.clj) (Service), [`deploy.sh`](https://github.com/datil/facephi-service/blob/master/deploy.sh) (Build), [`src/facephi_service/server.clj`](https://github.com/datil/facephi-service/blob/master/src/facephi_service/server.clj) (Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_server["Server<br/>HTTP entrypoint<br/>[server.clj]"]
  node_service["Service<br/>request flow<br/>[service.clj]"]
end

subgraph group_domain["Domain"]
  node_api_key["API Key<br/>auth domain<br/>[api_key.clj]"]
  node_block["Block<br/>control domain<br/>[block.clj]"]
  node_admin["Admin<br/>privileged ops<br/>[admin.clj]"]
  node_messages["Messages<br/>response formatting<br/>[messages.clj]"]
end

subgraph group_persistence["Persistence"]
  node_database[("Database<br/>db boundary<br/>[database.clj]")]
  node_sql_api_key["API Key SQL<br/>sql scripts<br/>[api_key.sql]"]
  node_sql_account["Account SQL<br/>sql scripts<br/>[user_account.sql]"]
  node_sql_block["Block SQL<br/>sql scripts<br/>[user_block.sql]"]
  node_sql_log["Log SQL<br/>sql scripts<br/>[user_log.sql]"]
  node_test_ds[("Test DB<br/>test datasource")]
  node_schema["Schema Init<br/>bootstrap sql<br/>[database.up.sql]"]
end

subgraph group_integration["Integrations"]
  node_facephi["FacePhi<br/>SDK adapter<br/>[facephi.clj]"]
end

subgraph group_ops["Ops"]
  node_conf["Config<br/>[conf.clj]"]
  node_build["Build<br/>packaging<br/>[deploy.sh]"]
end

node_server -->|"dispatches"| node_service
node_service -->|"authenticates"| node_api_key
node_service -->|"checks"| node_block
node_service -->|"routes"| node_admin
node_service -->|"validates biometrics"| node_facephi
node_service -->|"persists"| node_database
node_service -->|"formats"| node_messages
node_database -->|"uses"| node_sql_api_key
node_database -->|"uses"| node_sql_account
node_database -->|"uses"| node_sql_block
node_database -->|"uses"| node_sql_log
node_conf -->|"configures"| node_server
node_conf -->|"configures"| node_database
node_test_ds -.->|"substitutes"| node_database
node_build -->|"packages"| node_server
node_build -.->|"requires"| node_facephi
node_build -.->|"requires"| node_database
node_schema -->|"initializes"| node_database

click node_server "https://github.com/datil/facephi-service/blob/master/src/facephi_service/server.clj"
click node_service "https://github.com/datil/facephi-service/blob/master/src/facephi_service/service.clj"
click node_api_key "https://github.com/datil/facephi-service/blob/master/src/facephi_service/api_key.clj"
click node_block "https://github.com/datil/facephi-service/blob/master/src/facephi_service/block.clj"
click node_admin "https://github.com/datil/facephi-service/blob/master/src/facephi_service/admin.clj"
click node_messages "https://github.com/datil/facephi-service/blob/master/src/facephi_service/messages.clj"
click node_facephi "https://github.com/datil/facephi-service/blob/master/src/facephi_service/facephi.clj"
click node_database "https://github.com/datil/facephi-service/blob/master/src/facephi_service/database.clj"
click node_sql_api_key "https://github.com/datil/facephi-service/blob/master/src/facephi_service/sql/api_key.sql"
click node_sql_account "https://github.com/datil/facephi-service/blob/master/src/facephi_service/sql/user_account.sql"
click node_sql_block "https://github.com/datil/facephi-service/blob/master/src/facephi_service/sql/user_block.sql"
click node_sql_log "https://github.com/datil/facephi-service/blob/master/src/facephi_service/sql/user_log.sql"
click node_conf "https://github.com/datil/facephi-service/blob/master/src/facephi_service/conf.clj"
click node_test_ds "https://github.com/datil/facephi-service/blob/master/src/facephi_service/test_datasource.clj"
click node_build "https://github.com/datil/facephi-service/blob/master/deploy.sh"
click node_schema "https://github.com/datil/facephi-service/blob/master/resources/database.up.sql"

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_server,node_service toneBlue
class node_api_key,node_block,node_admin,node_messages toneAmber
class node_database,node_sql_api_key,node_sql_account,node_sql_block,node_sql_log,node_test_ds,node_schema toneMint
class node_facephi toneRose
class node_conf,node_build toneIndigo
```

## Components

### Runtime

Deployment and request entrypoints

- [Server](https://github.com/datil/facephi-service/blob/master/src/facephi_service/server.clj): HTTP entrypoint · Servlet and local runtime bootstrap for request handling · `src/facephi_service/server.clj`
- [Service](https://github.com/datil/facephi-service/blob/master/src/facephi_service/service.clj): request flow · Routes requests through domain logic and assembles responses · `src/facephi_service/service.clj`

### Domain

Business logic and service orchestration

- [API Key](https://github.com/datil/facephi-service/blob/master/src/facephi_service/api_key.clj): auth domain · Caller key lifecycle and validation logic · `src/facephi_service/api_key.clj`
- [Block](https://github.com/datil/facephi-service/blob/master/src/facephi_service/block.clj): control domain · User or session blocking rules · `src/facephi_service/block.clj`
- [Admin](https://github.com/datil/facephi-service/blob/master/src/facephi_service/admin.clj): privileged ops · Operator-facing management actions · `src/facephi_service/admin.clj`
- [Messages](https://github.com/datil/facephi-service/blob/master/src/facephi_service/messages.clj): response formatting · Shared messages, errors, and response payload shaping · `src/facephi_service/messages.clj`

### Persistence

Database access and SQL assets

- [Database](https://github.com/datil/facephi-service/blob/master/src/facephi_service/database.clj): db boundary · Oracle access layer and persistence coordination · `src/facephi_service/database.clj`
- [API Key SQL](https://github.com/datil/facephi-service/blob/master/src/facephi_service/sql/api_key.sql): sql scripts · SQL for key-related persistence operations · `src/facephi_service/sql/api_key.sql`
- [Account SQL](https://github.com/datil/facephi-service/blob/master/src/facephi_service/sql/user_account.sql): sql scripts · SQL for user account state · `src/facephi_service/sql/user_account.sql`
- [Block SQL](https://github.com/datil/facephi-service/blob/master/src/facephi_service/sql/user_block.sql): sql scripts · SQL for block state operations · `src/facephi_service/sql/user_block.sql`
- [Log SQL](https://github.com/datil/facephi-service/blob/master/src/facephi_service/sql/user_log.sql): sql scripts · SQL for user and operational logging · `src/facephi_service/sql/user_log.sql`
- [Test DB](https://github.com/datil/facephi-service/blob/master/src/facephi_service/test_datasource.clj): test datasource · Controlled datasource used by tests · `src/facephi_service/test_datasource.clj`
- [Schema Init](https://github.com/datil/facephi-service/blob/master/resources/database.up.sql): bootstrap sql · Initial database schema and provisioning script · `resources/database.up.sql`

### Integrations

External SDK and binary dependencies

- [FacePhi](https://github.com/datil/facephi-service/blob/master/src/facephi_service/facephi.clj): SDK adapter · Integration boundary to the biometric FacePhi SDK · `src/facephi_service/facephi.clj`

### Ops

Configuration, packaging, and deployment

- [Config](https://github.com/datil/facephi-service/blob/master/src/facephi_service/conf.clj): runtime config · Environment and service configuration loading · `src/facephi_service/conf.clj`
- [Build](https://github.com/datil/facephi-service/blob/master/deploy.sh): packaging · WAR packaging and deployment scripting · `deploy.sh`

## Connections

- Server → Service: dispatches · Bootstraps the service layer and handles requests
- Service → API Key: authenticates · Validates caller credentials before executing operations
- Service → Block: checks · Applies block or restriction rules during request handling
- Service → Admin: routes · Invokes privileged administrative actions
- Service → FacePhi: validates biometrics · Calls the biometric SDK adapter for FacePhi operations
- Service → Database: persists · Reads and writes service state through the persistence boundary
- Service → Messages: formats · Uses shared response and error messaging
- Database → API Key SQL: uses · Executes key-related SQL statements
- Database → Account SQL: uses · Executes account-state SQL statements
- Database → Block SQL: uses · Executes block-state SQL statements
- Database → Log SQL: uses · Executes logging SQL statements
- Config → Server: configures · Provides runtime settings to application startup
- Config → Database: configures · Supplies database and environment configuration
- Test DB → Database: substitutes · Replaces the production datasource in tests
- Build → Server: packages · Builds the deployable artifact around the application entrypoint
- Build → FacePhi: requires · Relies on externally installed FacePhi binaries
- Build → Database: requires · Relies on Oracle JDBC and environment-specific dependencies
- Schema Init → Database: initializes · Bootstraps the database schema used by the service