Developer and Operations Guide
How to run, verify, and release the two Agapi services without confusing their responsibilities.
Development work often crosses repository boundaries: a button in the admin web can call Symfony, a compatibility route can call the real-time service, and both systems can use the same business data. The goal of this guide is to make those boundaries visible before code or data is changed.
Repository map
| Working directory | What it starts | Why you need it |
|---|---|---|
api | Symfony admin API, member API, and a local PostgreSQL database. | Work on current server endpoints, shared records, payments, reports, messages, and integrations. |
agapi-member-booking | Admin web, compatibility API, real-time service, database, and pgAdmin. | Work on staff screens and business actions that have not moved fully to Symfony. |
docs | This Next.js/Fumadocs website. | Review business documentation and diagrams locally. |
The legacy agapi-member-booking/agapi/mobile frontend is not part of the
supported development flow in this guide.
Why both service stacks share a network
Both Compose files join an external Docker network called agapi. This lets the
admin/compatibility services and Symfony services reach one another by their
configured service addresses.
The repositories still run separate PostgreSQL containers by default. Check the selected environment settings before assuming that two local screens read the same database.
Local addresses
| Service | Default local address |
|---|---|
| Admin web | http://localhost:8088/admin |
| Compatibility API | http://localhost:8088/api/... |
| Real-time socket | ws://localhost:5555/ws |
| Symfony admin API | http://localhost/ |
| Symfony Swagger | http://localhost/docs |
| Symfony OpenAPI JSON | http://localhost/docs.json |
| Symfony member API | http://localhost:8080/ |
| Documentation site | http://localhost:3000 |
Guides
- Local Setup explains the safe startup order and health checks.
- Testing and Code Checks explains what each check protects and which suites belong to which repository.
- CI/CD and Deployment explains the real pipeline gates, manual steps, and environment differences.
Before changing a feature
- Start from the user's goal and identify the screen or client action.
- Follow the actual request to Symfony, compatibility HTTP, or real-time RPC.
- Search both repositories for the stored fields and action name.
- Reproduce the current behavior with the smallest relevant test.
- Change the owning code and update the matching narrative/API documentation.
- Verify partial-failure behavior when the action crosses a database, queue, or external provider boundary.
Never copy real environment values, member data, access tokens, or payment identifiers into documentation or test fixtures.