How datil/facephi-service works
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: database.clj Database · service.clj Service · deploy.sh Build · server.clj Server
Components 16
Runtime
Deployment and request entrypoints
Domain
Business logic and service orchestration
- API Key · Caller key lifecycle and validation logic
src/facephi_service/api_key.clj - Block · User or session blocking rules
src/facephi_service/block.clj - Admin · Operator-facing management actions
src/facephi_service/admin.clj - Messages · Shared messages, errors, and response payload shaping
src/facephi_service/messages.clj
Persistence
Database access and SQL assets
- Database · Oracle access layer and persistence coordination
src/facephi_service/database.clj - API Key SQL · SQL for key-related persistence operations
src/facephi_service/sql/api_key.sql - Account SQL · SQL for user account state
src/facephi_service/sql/user_account.sql - Block SQL · SQL for block state operations
src/facephi_service/sql/user_block.sql - Log SQL · SQL for user and operational logging
src/facephi_service/sql/user_log.sql - Test DB · Controlled datasource used by tests
src/facephi_service/test_datasource.clj - Schema Init · Initial database schema and provisioning script
resources/database.up.sql
Integrations
External SDK and binary dependencies
- FacePhi · Integration boundary to the biometric FacePhi SDK
src/facephi_service/facephi.clj
Connections 18
- 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